Part II Run-Time Library Routines 
(continued) 

This part contains descriptions of the Run-Time Library routines. 

Order Number: AA-Z505B-TE (Volume 5D) 

Order Number: QLZ55-GZ (Volumes 5C and 5D) 






Run-Time Library Routines 

MTH$xACOS 


MTH$xACOS—Arc Cosine of Angle 



Expressed in Radians 

Given the cosine of an angle, MTH$xACOS returns that angle (in 
radians). 

FORMAT 

MTHSACOS x 

MTH$DACOS x 

MTH$GACOS x 

MTH$HACOS h—radians ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$ACOS_R4 

MTH$DACOS_R7 

MTH$GACOS_R7 

MTH$HACOS_R8 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

VMS Usage: floating-point 

type: F— floating, D_ floating, G_floating 

access: write only 

mechanism: by value 

Angle in radians. The angle returned will be a value between 0 and PI. 
MTH$ACOS returns an F_ floating number. MTH$DACOS returns a D_ 
floating number. MTH$GACOS returns a G_floating number. Unlike the 
other three routines, MTH$HACOS returns the angle by reference in the 
h—radians argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_ floating, D_ floating, G_floating, H_ floating 

access: read only 

mechanism: by reference 

The cosine of the angle whose value (in radians) is to be returned. The 
x argument is the address of a floating-point number that is this cosine. 

The absolute value of x must be less than or equal to 1. For MTH$ACOS, 
x specifies an F_floating number. For MTH$DACOS, x specifies a D_ 
floating number. For MTH$GACOS, x specifies a G_floating number. For 
MTH$HACOS, x specifies an H_floating number. 
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Run-Time Library Routines 

MTH$xACOS 



h—radians 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Angle (in radians) whose cosine is specified by x. The h__radians argument is 
the address of an H_floating number that is this angle. MTH$HACOS writes 
the address of the angle into h—radians. The h_radians argument is used 
only by the MTH$HACOS routine. 

DESCRIPTION 

The angle in radians whose cosine is x is computed as: 

Value of x Value Returned 

0 PI/2 

1 0 

-1 PI 

0 < X < 1 zATAN(zSQRT(1-X 2 )/X) , where zAT AN and zSQRT are the Math 

Library arc tangent and square root routines, respectively, of the 
appropriate data type 

-1 < X< 0 zATAN(zSQRT(1-X 2 )/X) + PI 

1 < IXI The error MTH$INVARGMAT is signaled 

CONDITION 

VALUES 

SIGNALED 

SS$_ROPRAND Reserved operand. The MTH$xACOS routine 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit of 
one and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

MTH$_INVARGMAT Invalid argument. The absolute value of x is greater 

than 1. LIB$SIGNAL copies the floating-point 


reserved operand to the mechanism argument 

vector CHF$I_MCH_SAVR0/R1. The result is the 

floating-point reserved operand unless you have 

written a condition handler to change CHF$I_ 

MCH_SAVR0/R1. 
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Run-Time Library Routines 

MTH$xACOS 


EXAMPLES 


□ 


100 ! + 

! This BASIC program demonstrates the use of 
! MTH$AC0S. 

! - 

EXTERNAL REAL FUNCTION MTHIACOS 
DECLARE REAL COS.VALUE, ANGLE 
300 INPUT "Cosine value between -1 and +1 COS.VALUE 

400 IF (COS.VALUE < -1) OR (COS.VALUE > 1) 

THEN PRINT "Invalid cosine value" 

GOTO 300 

500 ANGLE = MTHIACOS( COS.VALUE ) 

PRINT "The angle with that cosine is "; ANGLE; "radians" 
32767 END 


This BASIC program prompts for a cosine value and determines the angle 
that has that cosine. The output generated by this program is as follows: 

$ RUN ACOS 

Cosine value betwen -1 and +1 ? -5 

The angle with that cosine is 1.0472 radians 


PROGRAM GETANGLE(INPUT,OUTPUT); 

{+> 

< This PASCAL program uses MTHIACOS to determine 
{ the angle which has the cosine given as input. 

{-> 

VAR 

COS : REAL; 

FUNCTION MTHIACOS(COS : REAL) : REAL; 

EXTERN; 

BEGIN 

WRITE('Cosine value between -1 and +1: '); 

READ (COS); 

WRITELN('The angle with that cosine is MTHIACOS(COS), 

' radians'); 

END. 


This PASCAL program prompts for a cosine value and determines the angle 
that has that cosine. The output generated by this program is as follows: 

| RUN ACOS 

Cosine value between -1 and +1: 5 

The angle with that cosine is 1.04720E+00 radians 
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Run-Time Library Routines 

MTH$xACOSD 


MTH$xACOSD—Arc Cosine of Angle 



Expressed in Degrees 

Given the cosine of an angle, MTH$xACOSD returns that angle (in 
degrees). 

FORMAT 

MTHSACOSD x 

MTHSDACOSD x 

MTH$GACOSD x 

MTH$HACOSD h—degrees ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$ACOSD_R4 

MTH$DACOSD_R7 

MTH$GACOSD_R7 

MTH$HACOSD_R8 

Each of the above JSB entries accepts as input one of the four floating-point 
types. 

RETURNS 

VMS Usage: floating-point 
type: F_floating, D_floating, G—floating 

access: write only 

mechanism: by value 

Angle in degrees. The angle returned will be a value between 0 and 180. 
MTH$ACOSD returns an F_floating number. MTH$DACOSD returns a 
D_floating number. MTH$GACOSD returns a G_floating number. Unlike 
the other three routines, MTH$HACOSD returns the angle by reference in 
the h_degrees argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, G_floating, D_floating, H_floating 

access: read only 

mechanism: by reference 

Cosine of the angle whose value (in degrees) is to be returned. The x 
argument is the address of a floating-point number that is this cosine. The 
absolute value of x must be less than or equal to 1. For MTH$ACOSD, 
x specifies an F—floating number. For MTH$DACOSD, x specifies a D_ 
floating number. For MTH$GACOSD, x specifies a G_floating number. For 
MTH$HACOSD, x specifies an H_floating number. 
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Run-Time Library Routines 

MTH$xACOSD 


h—degrees 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Angle (in degrees) whose cosine is specified by x. The h_degrees argument 
is the address of an H_floating number that is this angle. MTH$HACOSD 
writes the address of the angle into h_degrees. The h_degrees argument is 
used only by the MTH$HACOSD routine. 


DESCRIPTION The angle in degrees whose cosine is X is computed as: 


Value of x 

Angle returned 

0 

90 

1 

0 

-1 

180 

0 < X < 1 

zATAND(zSQRT(1-X 2 )/X) , where zATAND and zSQRT are the 
Math Library arc tangent and square root routines, respectively, 
of the appropriate data type 

1 

A 

X 

A 

o 

zATAND(zSQRT(1-X 2 )/X) + 180 

1 < IXI 

The error MTH$INVARGMAT is signaled 


CONDITION SS$_ROPRAND 

VALUES 

SIGNALED 


MTH$_INVARGMAT 


Reserved operand. The MTH$xACOSD routine 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit of 
one and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 


DIGITAL. 

Invalid argument: The absolute value of x is greater 
than 1. LIBSSIGNAL copies the floating-point 
reserved operand to the mechanism argument 

vector CHF$I_MCH_SAVR0/R1. The result is the 

floating-point reserved operand unless you have 

written a condition handler to change CHF$I_ 

MCH_SAVR0/R1. 
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Run-Time Library Routines 

MTH$xACOSD 


EXAMPLE 

PROGRAM ACOSDCINPUT,OUTPUT); 

{♦> 

{ This PASCAL program demonstrates the use of 
{ MTH$AC0SD. 

{-> 

FUNCTION MTH$AC0SD(COS : REAL): REAL; EXTERN; 

VAR 

COSINE : REAL; 

RET.STATUS : REAL; 

BEGIN 

COSINE := 0.5; 

RET.STATUS := MTH$ACOSD(COSINE); 

WRITELN('The angle, in degress, is: ', RET.STATUS); 
END. 


The output generated by this PASCAL example program is as follows: 

The angle, expressed in degrees, is: 6.00000E+01 
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Run-Time Library Routines 

MTH$xASIN 


MTH$xASIN—Arc Sine in Radians 

Given the sine of an angle, MTH$xASIN returns that angle (in 



radians). 

FORMAT 

MTHSASIN x 

MTHSDASIN x 

MTHSGASIN x 

MTHSHASIN h—radians ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$ASIN_R4 

MTH$DASIN_R7 

MTH$GASIN_R7 

MTH$HASIN_R8 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

VMS Usage: floating-point 

type: F_floating, D_floating, G—floating, 

access: write only 

mechanism: by value 

Angle in radians. The angle returned will be a value between -PI/2 and 
+PI/2. MTH$ASIN returns an F_floating number. MTH$DASIN returns 
a D_floating number. MTH$GASIN returns a G_floating number. Unlike 
the other three routines, MTH$HASIN returns the angle by reference in the 
h_radians argument. 

ARGUMENTS 

X 

VMS Usage, floating-point 

type: F_floating, D_floating, G—floating, H_floating 

access: read only 

mechanism: by reference 

The sine of the angle whose value (in radians) is to be returned. The x 
argument is the address of a floating-point number that is this sine. The 
absolute value of x must be less than or equal to 1. For MTH$ASIN, 
x specifies an F_floating number. For MTH$DASIN, x specifies a D_ 
floating number. For MTFI$GASIN, x specifies a G_floating number. For 
MTH$HASIN, x specifies an H_floating number. 


RTL-378 











Run-Time Library Routines 

MTH$xASIN 


h—radians 


VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
H_floating 
write only 
by reference 


Angle (in radians) whose sine is specified by x. The h_radians argument is 
the address of an H—floating number that is this angle. MTH$HASIN writes 
the address of the angle into h_radians. The h__radians argument is used 
only by the MTH$HASIN routine. 


DESCRIPTION The angle in radians whose sine is x is computed as: 


Value of x 

Angle returned 

0 


0 

1 


PI/2 

-1 


-PI/2 

0 < 

1 

IXI < 

zATANCX/zSQRT(l-X 2 )) , where zATAN and zSQRT are the Math 
Library arc tangent and square root routines, respectively, of the 
appropriate data type 

1 < 

IXI 

The error MTH$INVARGMAT is signaled 


CONDITION SS$_ROPRAND 

VALUES 

SIGNALED 


MTH$_INVARGMAT 


Reserved operand. The MTH$xASIN routine 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

Invalid argument: The absolute value of x is greater 
than 1. LIBSSIGNAL copies the floating-point 
reserved operand to the mechanism argument 

vector CHF$I_MCFLSAVR0/R1. The result is the 

floating-point reserved operand unless you have 

written a condition handler to change CHF$I_ 

MCH—SAVRO/R1. 
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Run-Time Library Routines 

MTH$xASIND 


MTH$xASIND—Arc Sine in Degrees 



Given the sine of an angle, MTH$xASIND returns that angle (in 
degrees). 

FORMAT 

MTHSASIND x 

MTHSDASIND x 

MTHSGASIND x 

MTHSHASIND h^degrees ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$ASIND_R4 

MTH$DASIND_R7 

MTH$GASIND_R7 

MTH$HASIND_R8 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H—floating 

access: write only 

mechanism: by value 

Angle in degrees. The angle returned will be a value between -90 and +90. 
MTH$ASIND returns an F_floating number. MTH$DASIND returns a 
D_floating number. MTH$GASIND returns a G_floating number. Unlike 
the other three routines, MTH$HASIND returns the angle by reference in the 
h— degrees argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G—floating, H—floating 

access: read only 

mechanism: by reference 

Sine of the angle whose value (in degrees) is to be returned. The x argument 
is the address of a floating-point number that is this sine. The absolute 
value of x must be less than or equal to 1. For MTH$ASIND, x specifies an 
F_floating number. For MTH$DASIND, x specifies a D_floating number. 

For MTH$GASIND, x specifies a G_floating number. For MTH$HASIND, x 
specifies an H—floating number. 
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Run-Time Library Routines 

MTH$xASIND 


DESCRIPTION 


CONDITION 

VALUES 

SIGNALED 


h—degrees 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Angle (in degrees) whose cosine is specified by x. The h_ degrees argument 
is the address of an H_floating number that is this angle. MTH$HASIND 
writes the address of the angle into h— degrees. The h— degrees argument is 
used only by the MTH$HASIND routine. 


The angle in degrees whose sine is X is computed as: 


Value of x 

Value returned 

0 


0 

1 


90 

-1 


-90 

0 < 

1 

IXI < 

zATAND(X/zSQRTfl-X 2 )) , where zATAND and zSQRT are the 
Math Library arc tangent and square root routines, respectively, 
of the appropriate data type 

1 < 

IXI 

The error MTH$INVARGMAT is signaled 


SS$_ROPRAND Reserved operand. The MTH$xASIND routine 

encountered a floating point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit of 
one and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

MTH$_INVARGMAT Invalid argument: The absolute value of x is greater 

than 1. LIB$SIGNAL copies the floating-point 
reserved operand to the mechanism argument 

vector CHF$I_MCH_SAVRO/R 1. The result is the 

floating-point reserved operand unless you have 

written a condition handler to change CHF$I_ 

MCH—SAVR0/R1. 
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Run-Time Library Routines 

MTH$xATAN 


MTH$xATAN—Arc Tangent in Radians 



Given the tangent of an angle, MTH$xATAN returns that angle (in 
radians). 

FORMAT 

MTHSATAN x 

MTH$DATAN x 

MTHSGATAN x 

MTHSHATAN h^radians ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$ATAN_R4 

MTH$DATAN_R7 

MTH$GATAN_R7 

MTH$HATAN_R8 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

VMS Usage: floating-point 

type: F—floating, D_floating, G—floating 

access: write only 

mechanism: by value 

Angle in radians. The angle returned will be a value between -PI/2 and 
+PI/2. MTH$ATAN returns an F_floating number. MTH$DATAN returns 
a D_floating number. MTH$GATAN returns a G_floating number. Unlike 
the other three routines, MTH$HATAN returns the angle by reference in the 
h_radians argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

The tangent of the angle whose value (in radians) is to be returned. The 
x argument is the address of a floating-point number that is this tangent. 

For MTH$ATAN, x specifies an F_floating number. For MTH$DATAN, x 
specifies a D_floating number. For MTH$GATAN, x specifies a G—floating 
number. For MTH$HATAN, x specifies an IT—floating number. 
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Run-Time Library Routines 

MTH$xATAN 


DESCRIPTION 


CONDITION 

VALUE 

SIGNALED 


h—radians 


VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Angle (in radians) whose tangent is specified by x. The h_radians argument 
is the address of an TLJloating number that is this angle. MTH$HATAN 
writes the address of the angle into h_radians. The h_radians argument is 
used only by the MTH$HATAN routine. 


In radians, the computation of the arc tangent function is based on the 
following identities: 

arctantt) = X - X 3 /3 + X 5 /5 - X 7 /7 + . . . 

arctan(X) = X + X*Q(X 2 ), 

where Q(Y) * - Y/3 + Y 2 /5 - Y 3 /7 + . . . 

arctan(X) = X*P(X 2 ). 

where P(Y) = 1 - Y/3 + Y 2 /5 - Y 3 /7 + . . . 
arctan(X) = PI/2 - arctan(l/X) 

arctan(X) = arctan(A) + arctan((X-A)/(1+A*X)) for any real A 

The angle in radians whose tangent is X is computed as: 


Value of X 

Angle Returned 

0 =< X=< 3/32 

X + X » Q(X 2 ) 

3/32 < X=< 11 

ATAN(A) + V* (P(V 2 )) , where A and ATAN(A) are chosen 
by table lookup and V = (X - A)/(l + A*X) 

11 < X 

PI/2 - W* (P(W 2 )) where W=l/X 

X < 0 

-zATAN(\X\) 


SS$_ROPRAND Reserved operand. The MTH$xATAN routine 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 
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Run-Time Library Routines 

MTH$xATAND 


MTH$xATAND—Arc Tangent in Degrees 



Given the tangent of an angle, MTH$xATAND returns that angle (in 
degrees). 

FORMAT 

MTH$ATAND x 

MTH$DATAND x 

MTH$GATAND x 

MTH$HATAND h—degrees ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$ATAND_R4 

MTH$DATAND_R7 

MTH$GATAND_R7 

MTH$HATAND_R8 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

VMS Usage: floating-point 

type: F_floating, D_floating, G—floating 

access: write only 

mechanism: by value 

Angle in degrees. The angle returned will be a value between -90 and +90. 
MTH$ATAND returns an F_floating number. MTH$DATAND returns a 

D_floating number. MTH$GATAND returns a G—floating number. Unlike 
the other three routines, MTH$HATAND returns the angle by reference in 
the h_degrees argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D—floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

The tangent of the angle whose value (in degrees) is to be returned. The x 
argument is the address of a floating-point number that is this tangent. For 
MTH$ATAND, x specifies an F_floating number. For MTH$DATAND, x 
specifies a D_floating number. For MTH$GATAND, x specifies a G_floating 
number. For MTH$HATAND, x specifies an FL_floating number. 
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Run-Time Library Routines 

MTH$xATAND 


DESCRIPTION 


CONDITION 

VALUE 

SIGNALED 


h—degrees 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Angle (in degrees) whose tangent is specified by x. The h_degrees argument 
is the address of an H_floating number that is this angle. MTH$HATAND 
writes the address of the angle into h_.degrees. The hLdegrees argument is 
used only by the MTH$HATAND routine. 


The computation of the arc tangent function is based on the following 
identities: 


arctand(X) 

arctand(X) 

where 

arctand(X) 

where 


= 180/PI(X - X 3 /3 ♦ X 5 /5 - X 7 /7 + ...) 

= 64*X + X*Q(X 2 ), 

Q(Y) = 180/PI* [(1- 64*PI/180)] - Y/3 + Y 2 /5 - 
Y 3 /7 + Y 4 /9 ... ] 

* X*P(X 2 ), 

P(Y) * 180/PI*Cl - Y/3 + Y 2 /5 - Y 3 /7 + 

Y 4 /9 ... ] 


arctand(X) = 90 - arctand(l/X) 


arctand(X) = arctand(A) + arctand((X - A)/(l + A*X)) 


The angle in degrees whose tangent is X is computed as: 


Tangent 

Angle Returned 

X=< 3/32 

64*X + X*Q(X 2 ) 

3/32 < X=< 11 

ATAND(A) + V*P(V 2 ) , where A and ATAND(A) are 
chosen by table lookup and V = (X - A)/(l + A*X) 

11 < X 

90 - W * (P(W 2 )) , where W=l/X 

X < 0 

-zATAND(\X\) 


SS$_ROPRAND Reserved operand. The MTH$xATAND routine 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 
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Run-Time Library Routines 

MTH$xATAN2 


MTH$xATAN2—Arc Tangent in Radians 



with Two Arguments 

Given y and x, MTH$xATAN2 returns the angle (in radians) whose 
tangent is given by the quotient of y and x, (y/x). 

FORMAT 

MTH$ATAN2 y ,x 

MTH$DATAN2 y ,x 

MTHSGATAN2 y ,x 

MTH$HATAN2 h^radians,y,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

RETURNS 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating 

access: write only 

mechanism: by value 

Angle in radians. MTH$ATAN2 returns an F_floating number. 
MTH$DATAN2 returns a D_floating number. MTH$GATAN2 returns a 

G_floating number. Unlike the other three routines, MTH$HATAN2 returns 
the angle by reference in the h_radians argument. 

ARGUMENTS 

y 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

Dividend. The y argument is the address of a floating-point number that 
is this dividend. For MTFI$ATAN2 / y specifies an F_floating number. For 
MTH$DATAN2, y specifies a D_floating number. For MTH$GATAN2, y 
specifies a G_floating number. For MTH$HATAN2, y specifies an H_floating 
number. 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

Divisor. The x argument is the address of a floating-point number that 
is this divisor. For MTH$ATAN2, x specifies an F_floating number. For 
MTH$DATAN2, x specifies a D_floating number. For MTH$GATAN2, x 
specifies a G_floating number. For MTH$HATAN2, x specifies an H_floating 
number. 
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Run-Time Library Routines 

MTH$xATAN2 


DESCRIPTION 


CONDITION 

VALUES 

SIGNALED 


h—radians 


VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Angle (in radians) whose tangent is specified by (y/x). The h_radians 
argument is the address of an TLJloating number that is this angle. 
MTH$HATAN2 writes the address of the angle into h—radians. The h_ 
radians argument is used only by the MTH$HATAN2 routine. 


The angle in radians whose tangent is Y/X is computed as follows and / is 
defined in the description of MTH$zCOSH. 


Value of Input Arguments 

Angle Returned 

X = 0 or Y/X > 2</ +1 > 

PI/2* (sign Y) 

X > 0 and Y/X =< 2</ +1 > 

zATAN(Y/X) 

X < Oand Y/X =< 2tf +1 > 

PI * (sign Y) + zATAN(Y/X) 


SS$_ROPRAND Reserved operand. The MTH$xATAN2 routine 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

MTH$_INVARGMAT Invalid argument: Both x and y are zero. 

LIB$SIGNAL copies the floating-point reserved 
operand to the mechanism argument vector 

CHF$I_MCH_SAVR0/R1. The result is the 

floating-point reserved operand unless you have 

written a condition handler to change CHF$I_ 

MCH—SAVRO/R1. 
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MTH$xATAIMD2—Arc Tangent in Degrees 



with Two Arguments 

Given y and x, MTH$xATAND2 returns the angle (in degrees) whose 
tangent is given by the quotient of y and x, (y/x). 

FORMAT 

MTH$ATAND2 y,x 

MTH$DATAND2 y,x 

MTH$GATAND2 y,x 

MTH$HATAND2 h^degrees,y,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

RETURNS 

VMS Usage: floating-point 
type: F_floating, D_floating, G_floating 

access: write only 

mechanism: by value 

Angle (in degrees). MTH$ATAND2 returns an F_floating number. 
MTH$DATAND2 returns a D_floating number. MTH$GATAND2 returns 
a G_floating number. Unlike the other three routines, MTH$HATAND2 
returns the angle by reference in the h— degrees argument. 

ARGUMENTS 

Y 

VMS Usage: floating-point 

type: F—floating, D_floating, G—floating, H—floating 

access: read only 

mechanism: by reference 

Dividend. The y argument is the address of a floating-point number that is 
this dividend. For MTH$ATAND2, y specifies an F_floating number. For 
MTFi$DATAND2, y specifies a D_floating number. For MTFf$GATAND2, 
y specifies a G_floating number. For MTH$HATAND2, y specifies an 

H_floating number. 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

Divisor. The x argument is the address of a floating-point number that is 
this divisor. For MTH$ATAND2, x specifies an F_floating number. For 
MTH$DATAND2, x specifies a D_floating number. For MTH$GATAND2, 
x specifies a G_floating number. For MTH$HATAND2, x specifies an Fi_ 
floating number. 
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DESCRIPTION 


CONDITION 

VALUES 

SIGNALED 


h—degrees 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Angle (in degrees) whose tangent is specified by (y/x). The h— degrees 
argument is the address of an H_floating number that is this angle. 
MTH$HATAND2 writes the address of the angle into h— degrees. The 
h— degrees argument is used only by the MTH$HATAND2 routine. 


The angle in degrees whose tangent is Y/X is computed below and where / is 
defined in the description of MTH$zCOSH. 


Value of Input Arguments 

Angle Returned 

X = 0 or Y/X > 2</ +1 > 

90 * (sign Y) 

X > 0 and Y/X =< 2<-f +1 > 

zATAND(Y/X) 

X < 0 and Y/X =< 2</ +1 > 

180 * (sign Y) + zATAND(Y/X) 


SS$_ROPRAND Reserved operand. The MTH$xATAND2 routine 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

MTH$_INVARGMAT Invalid argument: Both x and y are zero. 

LIB$SIGNAL copies the floating-point reserved 
operand to the mechanism argument vector 

CHF$I_MCH_SAVR0/R1. The result is the 

floating-point reserved operand unless you have 

written a condition handler to change CHF$I_ 

MCH_SAVR0/R1. 


RTL-389 










Run-Time Library Routines 

MTH$xATANH 


MTH$xATANH—Hyperbolic Arc Tangent 



Given the hyperbolic tangent of an angle, MTH$xATANH returns the 
hyperbolic arc tangent of that angle. 

FORMAT 

MTH$ATANH x 

MTH$DATANH x 

MTH$GATANH x 

MTH$HATANH h_atanh ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

RETURNS 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating 

access: write only 

mechanism: by value 

The hyperbolic arc tangent of x. MTH$ATANH returns an F_floating 
number. MTH$DATANH returns a D_floating number. MTH$GATANH 
returns a G_floating number. Unlike the other three routines, 
MTH$HATANH returns the hyperbolic arc tangent by reference in the 
h—atanh argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

Hyperbolic tangent of an angle. The x argument is the address of a floating¬ 
point number that is this hyperbolic tangent. For MTH$ATANH, x specifies 
an F_floating number. For MTH$DATANH, x specifies a D_floating number. 
For MTH$GATANH, x specifies a G_floating number. For MTH$HATANH, 
x specifies an H_floating number. 

h—atanh 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Hyperbolic arc tangent of the hyperbolic tangent specified by x. The h—atanh 
argument is the address of an H_floating number that is this hyperbolic 
tangent. MTH$HATANH writes the address of the hyperbolic tangent into 
h—atanh. The h—atanh argument is used only by the MTH$HATANH 
routine. 
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DESCRIPTION The hyperbolic arc tangent function is computed as follows: 

Value of x Value Returned 

IXI < 1 zATANHQO = zLOG((X+l)/(X-l)) /2 

IXI >= 1 An invalid argument is signaled 


CONDITION SSS—ROPRAND 

VALUES 

SIGNALED 



MTH$_INVARGMAT 



Reserved operand. The MTH$xATANH routine 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

Invalid argument: IXI >= 1 . LIBSSIGNAL 
copies the floating-point reserved operand to the 

mechanism argument vector CHF$I_MCH_SAVRO 

/R1. The result is the floating-point reserved 
operand unless you have written a condition 
handler to change CHF$I_MCH_SAVR0/R1. 
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MTH$CxABS—Complex Absolute Value 



MTH$CxABS returns the absolute value of a complex number (r,i). 

FORMAT 

MTH$CABS complex-number 

MTH$CDABS complex-number 

MTH$CGABS complex-number 

Each of the above three formats accepts as input one of the three floating¬ 
point complex types. 

RETURNS 

VMS Usage: floating-point 
type: F_floating, D_floating, G_floating 

access: write only 

mechanism: by value 

The absolute value of a complex number. MTH$CABS returns an F_floating 
number. MTH$CDABS returns a D_floating number. MTH$CGABS returns 
a G_floating number. 

ARGUMENT 

complex-number 

VMS Usage: complex_number 

type: F_floating complex, D_floating complex, G—floating 

complex 
access: read only 

mechanism: by reference 

A complex number (r,i), where r and i are both floating-point complex values. 
The complex-number argument is the address of this complex number. For 
MTH$CABS, complex-number specifies an F_floating complex number. For 
MTH$CDABS, complex-number specifies a D_floating complex number. For 
MTH$CGABS, complex-number specifies a G_floating complex number. 

DESCRIPTION 

The complex absolute value is computed as follows where MAX is the larger 
of Irl and lil, and MIN is the smaller of Irl and lil. 

result = MAX * SQRT ( (MIN/MAX) 2 + 1) 

CONDITION 

VALUES 

SIGNALED 

SS$_ROPRAND Reserved operand. The MTHSCxABS routine 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

MTH$_FLOOVEMAT Floating-point overflow in Math Library when both r 

and i are large. 
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EXAMPLES 


C This FORTRAN example forms the absolute value of an 
C F.floating complex number using MTH$CABS and the 
C FORTRAN random number generator RAN. 

C 

C Declare Z as a complex value and MTH$CABS as a REAL*4 value. 

C MTH$CABS will return the absolute value of Z: Z_NEW = MTH$CABS(Z). 

C- 

COMPLEX Z 

COMPLEX CMPLX 

REAL*4 Z_NEW,MTH$CABS 

INTEGER M 

M = 1234567 

C+ 

C Generate a random complex number with the FORTRAN generic CMPLX. 

C- 

Z = CMPLX(RAN(M).RAN(M)) 

C+ 

C Z is a complex number (r.i) with real part "r H and 
C imaginary part "i" . 

C- 

TYPE *, ' The complex number z is'.z 

TYPE *, ' It has real part'.REAL(Z)and imaginary part'.AIMAG(Z) 
TYPE *, ' ' 

C+ 

C Compute the complex absolute value of Z. 

C- 

Z.NEW = MTH$CABS(Z) 

TYPE *, ' The complex absolute value of'.z,' is',Z_NEW 
END 


This example uses an F_floating complex number for complex-number. The 
output of this FORTRAN example is as follows: 

The complex number z is (0.8535407,0.2043402) 

It has real part 0.8535407 and imaginary part 0.2043402 

The complex absolute value of (0.8535407,0.2043402) is 0.8776597 
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C This FORTRAN example forms the absolute 
C value of a G_floating complex number using 
C MTHlCGABS and the FORTRAN random number 

C generator RAN. 

C 

C Declare Z as a complex value and MTH$CGABS as a 

C REAL*8 value. MTH$CGABS will return the absolute 

C value of Z: Z.NEW = MTH$CGABS(Z). 

C- 


C0MPLEX*16 Z 

REAL*8 Z.NEW,MTHlCGABS 

Generate a random complex number with the FORTRAN 
generic CMPLX. 

Z = (12.34567890123,45.536376385345) 

TYPE *, ' The complex number z is',z 
TYPE *. • ' 

Compute the complex absolute value of Z. 

Z.NEW = MTH$CGABS(Z) 

TYPE *, ' The complex absolute value of',z,' is',Z.NEW 
END 


This FORTRAN example uses a G_floating complex number for complex- 
number. Because this example uses a Gloating number, it must be 
compiled as follows: 

$ FORTRAN/G MTHEX.FOR 

Notice the difference in the precision of the output generated: 

The complex number z is (12.3456789012300,45.5363763853450) 

The complex absolute value of (12.3456789012300,45.5363763853450) is 
47.1802645376230 


RTL-394 





Run-Time Library Routines 

MTHSCxCOS 


MTH$CxCOS—Complex Cosine 



MTH$CxCOS returns the complex cosine of a complex number. 

FORMAT 

MTH$CCOS complex-number 

MTH$CDCOS complex-cosine ,complex-number 
MTH$CGCOS complex-cosine, complex-number 

Each of the above three formats accepts as input one of the three floating¬ 
point types. 

RETURNS 

VMS Usage: complex_number 
type: F_floating complex 

access: write only 

mechanism: by value 

The complex cosine of the complex input number. MTH$CCOS returns an 
F_floating complex number. MTH$CDCOS returns a D_floating complex 
number by reference in the complex-cosine argument. MTH$CGCOS returns 
a G_floating complex number by reference in the complex-cosine argument. 

ARGUMENTS 

complex-number 

VMS Usage: complex_number 

type: F_floating complex, D_floating complex, G_floating 

complex 
access: read only 

mechanism: by reference 

A complex number (r,i) where r and i are floating-point numbers. The 
complex-number argument is the address of this complex number. For 
MTH$CCOS, complex-number specifies an F_floating complex number. For 
MTH$CDCOS, complex-number specifies a D_floating complex number. For 
MTH$CGCOS, complex-number specifies a G_floating complex number. 

complex-cosine 

VMS Usage: complex_number 

type: D_floating complex, G_floating complex 

access: write only 

mechanism: by reference 

Complex cosine of the complex-number. The complex cosine routines that 
have D_floating and G_floating complex input values write the address of 
the complex cosine into the complex-cosine argument. For MTH$CDCOS, 
the complex-cosine argument specifies a D_floating complex number. 

For MTH$CGCOS, the complex-number argument specifies a G_floating 
complex number. For MTH$CCOS, complex-number is not used. 

DESCRIPTION 

The complex cosine is calculated as follows: 

result = (COS(r) * COSH(i), -SIN(r) * SINH(i)) 
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CONDITION SS$_ROPRAND 

VALUES 

SIGNALED 


MTH$_FLOOVEMAT 


Reserved operand. The MTH$CxCOS routine 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

Floating-point overflow in Math Library: the 
absolute value of i is greater than about 88.029 
for F_floating and D_floating values or greater than 
709.089 for G_floating values. 


EXAMPLES 


C This FORTRAN example forms the complex 
C cosine of an F.floating complex number using 
C MTHlCCOS and the FORTRAN random number 

C generator RAN. 

C 

C Declare Z and MTHlCCOS as complex values. 

C MTH$CC0S will return the cosine value of 
C Z: Z.NEW = MTH$CC0S(Z) 

C- 

COMPLEX Z,Z.NEW,MTH$CC0S 
COMPLEX CMPLX 
INTEGER M 
M = 1234567 

C+ 

C Generate a random complex number with the 

C FORTRAN generic CMPLX. 

C- 

Z = CMPLX(RAN(M),RAN(M)) 

C+ 

C Z is a complex number (r,i) with real part "r" and 

C imaginary part "i". 

C- 

TYPE *, ' The complex number z is'.z 

TYPE *, ' It has real part'.REAL(Z)and imaginary part',AIMAG(Z) 
TYPE ' 

C+ 

C Compute the complex cosine value of Z. 

C- 

Z.NEW = MTH$CC0S(Z) 

TYPE *, ' The complex cosine value of'.z,' is',Z.NEW 
END 


This FORTRAN example demonstrates the use of MTH$CxCOS, using the 
MTH$CCOS entry point. The output of this program is as follows: 

The complex number z is (0.8535407,0.2043402) 

It has real part 0.8535407 and imaginary part 0.2043402 

The complex cosine value of (0.8535407,0.2043402) is (0.6710899,-0.1550672) 
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C This FORTRAN example forms the complex 
C cosine of a D_floating complex number using 
C MTH$CDC0S and the FORTRAN random number 

C generator RAN. 

C 

C Declare Z and MTH$CDC0S as complex values. 

C MTH$CDCOS will return the cosine value of 
C Z: Z.NEW = MTH$CDCOS(Z) 

C- 

C0MPLEX*16 Z,Z.NEW.MTH$CDCOS 
COMPLEX*16 DCMPLX 
INTEGER M 
M = 1234567 
C+ 

C Generate a random complex number with the 

C FORTRAN generic DCMPLX. 

C- 

Z = DCMPLX(RAN(M),RAN(M)) 

C+ 

C Z is a complex number (r.i) with real part "r" and 

C imaginary part "i". 

C- 

TYPE *, ' The complex number z is'.z 
TYPE *, ' ' 

C+ 

Compute the complex cosine value of Z. 

Z.NEW = MTH$CDC0S(Z) 

TYPE *, ' The complex cosine value of'.z,' is',Z.NEW 
END 


This FORTRAN example program demonstrates the use of MTH$CxCOS, 
using the MTH$CDCOS entry point. Notice the high precision of the output 
generated: 

The complex number z is (0.8535407185554504,0.2043401598930359) 

The complex cosine value of (0.8535407185554504,0.2043401598930359) is 
(0.6710899028500762,-0.1550672019621661) 
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MTH$CxEXP—Complex Exponential 



MTH$CxEXP returns the complex exponential of a complex number. 

FORMAT 

MTH$CEXPP complex-number 

MTH$CDEXP complex-exp ,complex-number 
MTH$CGEXP complex-exp , complex-number 

Each of the above three formats accepts as input one of the three floating¬ 
point complex types. 

RETURNS 

VMS Usage: complex_number 
type: F_floating complex 

access: write only 

mechanism: by value 

Complex exponential of the complex input number. MTH$CEXP returns an 
F_floating complex number. MTHE$CDEXP returns a D—floating complex 
number by reference in the complex-exp argument. MTH$CGEXP returns a 
G_floating complex number in the complex-exp argument. 

ARGUMENTS 

complex-number 

VMS Usage: complex_number 

type: F_floating complex, D_floating complex, G_floating 

complex 
access: read only 

mechanism: by reference 

Complex number whose complex exponential is to be returned. This complex 
number has the form (r,i), where “r" is the real part and "i" is the imaginary 
part. The complex-number argument is the address of this complex 
number. For MTH$CEXP, complex-number specifies an F_JIoating number. 
For MTH$CDEXP, complex-number specifies a D_floating number. For 
MTH$CGEXP, complex-number specifies a G—floating number. 

complex-exp 

VMS Usage: complex_number 

type: D_floating complex, G—floating complex 

access: write only 

mechanism: by reference 

Complex exponential of complex-number. The complex exponential routines 
that have D_floating complex and G—floating complex input values write the 
complex-exp into this argument. For MTH$CDEXP, complex-exp argument 
specifies a D_floating complex number. For MTH$CGEXP, complex-exp 
specifies a G—floating complex number. For MTH$CCEXP, complex-exp is 
not used. 


DESCRIPTION The complex exponential is computed as follows: 

complex-exp * (EXP(r)*COS(i). EXP(r)*SIN(i)) 
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CONDITION SSS—ROPRAND 

VALUES 

SIGNALED 


encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 


Reserved operand. The MTH$CxEXP routine 


DIGITAL. 


MTH$_FLOOVEMAT 


Floating-point overflow in Math Library: the 
absolute value of r is greater than about 88.029 
for F_floating and D_floating values or greater than 
about 709.089 for G_floating values. 


EXAMPLES 


C This FORTRAN example forms the complex exponential 
C of an F_floating complex number using MTH$CEXP 
C and the FORTRAN random number generator RAN. 

C 

C Declare Z and MTH$CEXP as complex values. MTH$CEXP 
C will return the exponential value of Z: Z_NEW = MTH$CEXP(Z) 


C- 


COMPLEX Z.Z_NEW.MTH$CEXP 
COMPLEX CMPLX 
INTEGER M 
M = 1234567 

C+ 

C Generate a random complex number with the 
C FORTRAN generic CMPLX. 


C- 


Z = CMPLX(RAN(M).RAN(M)) 

C+ 

C Z is a complex number (r.i) with real part "r" 

C and imaginary part "i". 

C- 

TYPE *, ' The complex number z is'.z 

TYPE *, ' It has real part'.REAL(Z)and imaginary part',AIMAG(Z) 
TYPE ' 


C+ 

C Compute the complex exponential value of Z. 
C- 


Z.NEW = MTH$CEXP(Z) 

TYPE *, ' The complex exponential value of'.z,' is',Z_NEW 
END 


This FORTRAN program demonstrates the use of MTH$CEXP as a function 
call. The output generated by this example is as follows: 

The complex number z is (0.8535407,0.2043402) 

It has real part 0.8535407 and imaginary part 0.2043402 

The complex exponential value of (0.8535407,0.2043402) is (2.299097,0.4764476) 
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This FORTRAN example forms the complex exponential 
of a G_floating complex number using MTH$CGEXP 
and the FORTRAN random number generator RAN. 

Declare Z and MTH$CGEXP as complex values. 
MTHtCGEXP will return the exponential value 
of Z: CALL MTH$CGEXP(Z_NEW,Z) 


COMPLEX*16 Z,Z_NEW 
COMPLEX*16 MTH$GCMPLX 
REAL*8 R.I 
INTEGER M 
M = 1234567 


Generate a random complex number with the FORTRAN 
generic CMPLX. 

R = RAN(M) 

I = RAN(M) 

Z = MTH$GCMPLX(R.I) 

TYPE *, ' The complex number z is'.z 
TYPE *, ' ' 

Compute the complex exponential value of Z. 

CALL MTHlCGEXP(Z_NEW,Z) 

TYPE *, ' The complex exponential value of'.z,' is',Z_NEW 
END 


This FORTRAN example demonstrates how to access MTH$CGEXP as a 
procedure call. Because G—floating numbers are used, this program must be 
compiled using the command "FORTRAN/G filename". 

Notice the high precision of the output generated: 

The complex number z is (0.853540718555450,0.204340159893036) 

The complex exponential value of (0.853540718555450,0.204340159893036) is 
(2.29909677719458,0.476447678044977) 
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MTH$CxLOG—Complex Natural Logarithm 



MTH$CxL0G returns the complex natural logarithm of a complex 
number. 

FORMAT 

MTH$CLOG complex-number 

MTH$CDLOG complex-natlog ,complex-number 
MTH$CGLOG complex-natlog,complex-number 

Each of the above three formats accepts as input one of the three floating¬ 
point complex types. 

RETURNS 

VMS Usage: complex_number 
type: F_floating complex 

access: write only 

mechanism: by value 

The complex natural logarithm of a complex number. MTH$CLOG returns 
an F_floating complex number. MTH$CDLOG returns a D_floating complex- 
number by reference in the complex-natlog argument. MTH$CGLOG returns 
a G_floating complex number by reference in the complex-natlog argument. 

ARGUMENTS 

complex-number 

VMS Usage: complex_number 

type: F_floating complex, D_floating complex, G_floating 

complex 
access: read only 

mechanism: by reference 

Complex number whose complex natural logarithm is to be returned. This 
complex number has the form (r,i), where ”r” is the real part and ”i” is 
the imaginary part. The complex-number argument is the address of this 
complex number. For MTH$CLOG, complex-number specifies an F—floating 
number. For MTH$CDLOG, complex-number specifies a D_floating number. 
For MTH$CGLOG, complex-number specifies a G_floating number. 

complex-natlog 

VMS Usage: complex_number 

type: D_floating complex, G_floating complex 

access: write only 

mechanism: by reference 

Natural logarithm of the complex number specified by complex-number. 

The complex natural logarithm routines that have D_Jloating complex and 
G_floating complex input values write the address of the complex natural 
logarithm into complex-natlog. For MTH$CDLOG, the complex-natlog 
argument specifies a D_floating complex number. For MTH$CGLOG, the 
complex-natlog argument specifies a G_floating complex number. For 
MTH$CLOG, complex-natlog is not used. 
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DESCRIPTION The complex natural logarithm is computed as follows: 

CLOG(x) = (LOG(CABS(x)), ATAN2(i,r)) 


CONDITION SS$_ROPRAND 

VALUE 

SIGNALED 


Reserved operand. The MTH$CxLOG routine 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 


EXAMPLES 


C This FORTRAN example forms the complex logarithm 
C of a D_floating complex number by using MTH$CDLOG 

C and the FORTRAN random number generator RAN. 

C 

C Declare Z and MTH$CDLOG as complex values. Then MTH$CDLOG 
c will return the logarithm of Z: CALL MTH$CDLOG(Z_NEW,Z). 

C 

C Declare Z,Z_L0G, and MTH$DCMPLX as complex values, 

C and R and I as real values. MTH$DCMPLX takes two real 
C arguments and returns one complex number. 

C 

C Given a complex number Z, MTH$CDLOG(Z) returns the 

C complex natural logarithm of Z. 

C- 

COMPLEX*16 Z,Z_NEW,MTH$DCMPLX 
REAL*8 R,I 

R = 3.1425637846746565 
I = 7.43678469887 
Z = MTH$DCMPLX(R,I) 

C+ 

C Z is a complex number (r.i) with real part "r" and imaginary 
C part "i". 

C- 

TYPE *, ' The complex number z is'.z 
TYPE *. ' ' 

CALL MTH$CDLOG(Z_NEW,Z) 

TYPE The complex logarithm of'.z,' is',Z_NEW 
END 


This FORTRAN example program uses MTH$CDLOG by calling it as a 
procedure. The output generated by this program is as follows: 

The complex number z is (3.142563784674657,7.436784698870000) 

The complex logarithm of (3.142563784674657,7.436784698870000) is 
(2.088587642177504,1.170985519274141) 


Additional examples of using MTH$CLOG from VAX MACRO (using both 
the CALLS and the CALLG instructions) appear in Section 4.7. 
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MTH$xCMPLX—Complex Number Made 



from Floating-Point 

MTH$xCMPLX returns a complex number from two floating-point 
input values. 

FORMAT 

MTH$CMPLX real-part Jmag-part 

MTH $ DC M P LX complx, real-part , imag-part 
MTH$GCMPLX complx ,real-part ,imag-part 

Each of the above three formats accepts as input one of three floating-point 
types. 

RETURNS 

VMS Usage: complex_number 
type: F_floating complex number 

access: write only 

mechanism: by value 

A complex number. MTH$CMPLX returns an F_floating complex number. 
MTH$DCMPLX returns a D_floating complex number by reference in the 
complx argument. MTH$GCMPLX returns a G_floating complex number by 
reference in the complx argument. 

ARGUMENTS 

real-part 

VMS Usage: floating-point 
type: F_floating, D_floating, G_floating 

access: write only 

mechanism: by reference 

Real part of a complex number. The real-part argument is the address of a 
floating-point number that contains this real part, r of (r,i). For MTH$CMPLX, 
real-part specifies an F_floating number. For MTH$DCMPLX, real-part 
specifies a D_floating number. For MTH$GCMPLX, real-part specifies a 

G_floating number. 

imag-part 

VMS Usage: floating-point 

type: F—floating, D_floating, G_floating 

access. write only 

mechanism: by reference 

Imaginary part of a complex number. The imag-parg argument is the 
address of a floating-point number that contains this imaginary part, i 
of (r,i). For MTH$CMPLX, imag-part specifies an F_floating number. 

For MTH$DCMPLX, imag-part specifies a D_ floating number. For 
MTH$GCMPLX, imag-part specifies a G_ floating number. 
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complx 

VMS Usage: complex_number 

type: D_floating complex, G_floating complex 

access: write only 

mechanism: by reference 

The floating-point complex value of a complex number. The complex 
exponential functions that have D_Jfloating complex and G_floating complex 
input values write the address of this floating-point complex value into 
complx. For MTH$DCMPLX, complx specifies a D_floating complex 
number. For MTH$GCMPLX, complx specifies a G_floating complex 
number. For MTH$CMPLX, complx is not used. 


CONDITION SS$_ROPRAND 

VALUE 

SIGNALED 


Reserved operand. The MTH$xCMPL routine 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 


EXAMPLES 


C This FORTRAN example forms two F.floating 
C point complex numbers using MTH$CMPLX 
C and the FORTRAN random number generator RAN. 

C 

C Declare Z and MTH$CMPLX as complex values, and R 

C and I as real values. MTH$CMPLX takes two real 

C F.floating point values and returns one C0MPLEX*8 number. 

C 

C Note, since CMPLX is a generic name in FORTRAN, it would be sufficient 

C to use CMPLX. CMPLX must be declare to be of type C0MPLEX*8. 

C 

C Z * CMPLX(R.I) 

C- 

COMPLEX Z,MTH$CMPLX,CMPLX 
REAL*4 R,I 
INTEGER M 
M = 1234567 

R = RAN(M) 

I = RAN(M) 

Z = MTH$CMPLX(R,I) 

C+ 

C Z is a complex number (r,i) with real part "r" and 
C imaginary part "i". 

C- 

TYPE *, ' The two input values are:',R,I 
TYPE *, ' The complex number z is'.z 
z = CMPLX (RAN (M) , RAN (M)) 

TYPE ' 

TYPE *, ' Using the FORTRAN generic CMPLX with random R and I: 1 

TYPE *, ' The complex number z is'.z 

END 
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This FORTRAN example program demonstrates the use of MTH$CMPLX. 
The output generated by this program is as follows: 

The two input values are: 0.8535407 0.2043402 

The complex number z is (0.8535407,0.2043402) 

Using the FORTRAN generic CMPLX with random R and I: 

The complex number z is (0.5722565,0.1857677) 


a c+ 

C This FORTRAN example forms two D.floating 
C point complex numbers using MTH$CMPLX 
C and the FORTRAN random number generator RAN. 

C 

C Declare Z and MTH$DCMPLX as complex values, and R 

C and I as real values. MTH$DCMPLX takes two real 

C D.floating point values and returns one 

C COMPLEX*16 number. 

C 

C- 

C0MPLEX*16 Z 
REAL*8 R,I 
INTEGER M 
M = 1234567 
R = RAN(M) 

I = RAN(M) 

CALL MTH$DCMPLX(Z,R,I) 

C+ 

C Z is a complex number (r,i) with real part "r" and imaginary 
C part "i". 

C- 

TYPE *, ' The two input values are:',R,I 

TYPE *, ' The complex number z is'.Z 

END 


This FORTRAN example demonstrates how to make a procedure call 
to MTH$DCMPLX. Notice the difference in the precision of the output 
generated. 

The two input values are: 0.8535407185554504 0.2043401598930359 

The complex number z is (0.8535407185554504,0.2043401598930359) 
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MTH$xCONJG—Conjugate of a Complex 



Number 

MTH$xCONJG returns the complex conjugate (r,-i) of a complex 
number (r,i). 

FORMAT 

MTH$CONJG complex-number 

MTH$DCONJG complex-conjugate complex- 
number 

MTH$GCONJG complex-conjugate complex- 
number 

Each of the above three formats accepts as input one of the three floating¬ 
point complex types. 

RETURNS 

VMS Usage: complex_number 
type: F_floating complex 

access: write only 

mechanism: by value 

Complex conjugate of a complex number. MTH$CONJG returns an F_ 
floating complex number. MTH$DCONJG returns a D—floating complex 
number by reference in the complex-conjugate argument. MTH$GCONJG 
returns a G_floating complex number by reference in the complex-conjugate 
argument. 

ARGUMENTS 

complex-number 

VMS Usage: complex-number 

type: F_floating complex, D_floating complex, G—floating 

complex 
access: read only 

mechanism: by reference 

A complex number (r,i), where r and i are floating-point numbers. The 
complex-number argument is the address of this floating-point complex 
number. For MTH$CONJG, complex-number specifies an F—floating 
number. For MTH$DCONJG, complex-number specifies a D_floating 
number. For MTH$GCONJG, complex-number specifies a G_floating 
number. 

complex-conjugate 

VMS Usage: complex—number 

type: D_floating complex, G—floating complex 

access: write only 

mechanism: by reference 

The complex conjugate (r,-i) of the complex number specified by complex- 
number. MTH$DCONJG and MTH$GCONJG write the address of this 
complex conjugate into complex-conjugate. For MTH$DCONJG, the 
complex-conjugate argument specifies the address of a D—floating complex 
number. For MTH$GCONJG, the complex-conjugate argument specifies 
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the address of a G_floating complex number. For MTH$CONJG, complex- 
conjugate is not used. 


CONDITION SS$_ROPRAND 

VALUE 

SIGNALED 


Reserved operand. The MTHSxCONJG routine 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 


EXAMPLE 

C+ 

C This FORTRAN example forms the complex conjugate 
C of a G.floating complex number using MTH$GCONJG 
C and the FORTRAN random number generator RAN. 

C 

C Declare Z, Z_NEW, and MTH$GCONJG as a complex values. 

C MTH$GCONJG will return the complex conjugate 
C value of Z: Z.NEW = MTH$GCONJG(Z). 

C- 

COMPLEX*16 Z.Z.NEW.MTH$GCONJG 
COMPLEX*16 MTH$GCMPLX 
REAL*8 R,I.MTH$GREAL,MTH$GIMAG 
INTEGER M 
M = 1234667 

C+ 

C Generate a random complex number with the 
C FORTRAN generic CMPLX. 

C- 

R = RAN(M) 

I = RAN(M) 

Z = MTH$GCMPLX(R,1) 

TYPE *, ' The complex number z is',z 
TYPE 1,MTH$GREAL(Z),MTH$GIMAG(Z) 

1 FORMAT(' with real part '.F20.16,' and imaginary part',F20.16) 

TYPE *, ' ' 

C+ 

C Compute the complex absolute value of Z. 

C- 

Z.NEW = MTH$GCONJG(Z) 

TYPE *, ' The complex conjugate value of'.z,' is',Z.NEW 
TYPE 1.MTH$GREAL(Z.NEW),MTH$GIMAG(Z.NEW) 

END 


This FORTRAN example demonstrates how to make a function call to 
MTH$GCONJG. Because G_floating numbers are used, the examples must be 
compiled with the statement "FORTRAN/G filename". 

The output generated by this program is as follows: 

The complex number z is (0.863540718656460,0.204340169893036) 
with real part 0.8535407185554504 and imaginary part 0.2043401598930359 
The complex conjugate value of (0.853540718555450,0.204340159893036) is 
(0.853540718555450.-0.204340159893036) 

with real part 0.8535407185554504 and imaginary part -0.2043401598930359 
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MTH$xCOS—Cosine of Angle Expressed 



in Radians 

MTH$xCOS returns the cosine of a given angle (in radians). 

FORMAT 

MTHSCOS x 

MTH$DCOS x 

MTH$GCOS x 

MTH$HCOS h—cosine ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$COS_R4 

MTH$DCOS_R7 

MTH$GCOS_R7 

MTH$HCOS_R5 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

VMS Usage: floating-point 

type: F—floating, D—floating, G—floating 

access: write only 

mechanism: by value 

Cosine of the angle. MTH$COS returns an F_floating number. MTH$DCOS 
returns a D—floating number. MTH$GCOS returns a G_floating number. 
Unlike the other three routines, MTH$HCOS returns the cosine by reference 
in the h_cosine argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

The angle in radians. The x argument is the address of a floating-point 
number. For MTH$COS, x is an F_floating number. For MTH$DCOS, x 
specifies a D_floating number. For MTH$GCOS, x specifies a G_floating 
number. For MTH$HCOS, x specifies an H_floating number. 
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h—cosine 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Cosine of the angle specified by x. The h__cosine argument is the address of 
an H_floating number that is this cosine. MTH$HCOS writes the address 
of the cosine into h_cosine. The h_cosine argument is used only by the 
MTH$HCOS routine. 

DESCRIPTION 

See the MTH$xSINCOS routine for the algorithm which is used to compute 
the cosine. 

CONDITION 

VALUE 

SIGNALED 

SS$_ROPRAND Reserved operand. The MTH$xCOS procedure 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 


reserved operands are reserved for future use by 
DIGITAL. 
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MTH$xCOSD—Cosine of Angle Expressed 



in Degrees 

MTH$xCOSD returns the cosine of a given angle (in degrees). 

FORMAT 

MTHSCOSD x 

MTH$DCOSD x 

MTHSGCOSD x 

MTH$HCOSD h—cosine ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$COSD_R4 

MTH$DCOSD_R7 

MTH$GCOSD_R7 

MTH$HCOSD_R5 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating 

access: write only 

mechanism: by value 

Cosine of the angle. MTH$COSD returns an F_floating number. 
MTH$DCOSD returns a D_floating number. MTH$GCOSD returns a 

G_floating number. Unlike the other three routines, MTH$HCOSD returns 
the angle by reference in the h— degrees argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G—floating, H_ floating 

access: read only 

mechanism: by reference 

Angle (in degrees). The x argument is the address of a floating-point number. 
For MTH$COSD, x specifies an F_floating number. For MTH$DCOSD, x 
specifies a D_floating number. For MTH$GCOSD, x specifies a G_floating 
number. For MTH$HCOSD, x specifies an H—floating number. 
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h— cosine 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Cosine of the angle specified by x. The h_cosine argument is the address of 
an H_floating number that is this cosine. MTH$HCOSD writes this cosine 
into h_cosine. The h—cosine argument is used only by the MTH$HCOSD 
routine. 

DESCRIPTION 

See the MTH$SINCOSD routine for the algorithm which is used to compute 
the cosine. 

CONDITION 

VALUE 

SIGNALED 

SS$_ROPRAND Reserved operand. The MTHSxCOSD procedure 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 


reserved operands are reserved for future use by 
DIGITAL. 
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MTH$xCOSH—Hyperbolic Cosine 



MTH$xCOSH returns the hyperbolic cosine of the input value. 

FORMAT 

MTH$COSH x 

MTHSDCOSH x 

MTHSGCOSH x 

MTHSHCOSH h—cosh ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

RETURNS 

VMS Usage: floating-point 

type: F_floating, D_floating, G—floating 

access: write only 

mechanism: by value 

The hyperbolic cosine of the input value x. MTH$COSH returns an F_ 
floating number. MTH$DCOSH returns a D—floating number. MTH$GCOSH 
returns a G_floating number. Unlike the other three routines, MTH$HCOSH 
returns the hyperbolic cosine by reference in the h_cosh argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D—floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

The input value. The x argument is the address of this input value. For 
MTH$COSH, x specifies an F_floating number. For MTH$DCOSH, x 
specifies a D—floating number. For MTH$GCOSH, x specifies a G_floating 
number. For MTH$HCOSH, x specifies an H_floating number. 

h—cosh 

VMS Usage: floating-point 
type: H—floating 

access: write only 

mechanism: by reference 

Hyperbolic cosine of the input value specified by x. The h_cosh argument 
is the address of an H_floating number that is this hyperbolic cosine. 
MTH$HCOSH writes the address of the hyperbolic cosine into h—cosh. The 
h_cosh argument is used only by the MTH$HCOSH routine. 


DESCRIPTION Computation of the hyperbolic cosine depends on the magnitude of the input 
argument. The range of the function is partitioned using four data-type- 
dependent constants: a(z), b(z), c(z), and d(z). The subscript z indicates the 
data type. The constants depend on the number of exponent bits ( e) and the 
number of fraction bits (/) associated with the data type (z). 
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CONDITION 

VALUES 

SIGNALED 


The values of e and / are: 


z 

e 

f 

F 

8 

24 

D 

8 

56 

G 

11 

53 

H 

15 

1 13 


The values of the constants in terms of e and / are: 


Variable 

Value 

a(z) 

2<-//2> 

b(z) 

CEILING[(f+iy2*/«('2; ] for F,D, and G 


(f+l)/2*ln(2) for H 

c(z) 

( 2 (e-i)-i ),ln(2) 

d(z) 

c(zhln(2) 


Based on the above definitions, zCOSH(X) is computed as follows: 


Value of X 


Value Returned 

IXI < a(z) 


1 

a(z) =< IXI < 

.25 

Computed using a power series expansion in IXI 2 

.25 =< IXI < 

b(z) 

(zEXP(\X\) + l/zEXP(\X\))/2 

<3- 

II 

A 

* 

A 

c(z) 

zEXP(\X\)/2 

c(z)=< IXI < 

d(z) 

zEXP(\X\-ln(2)) 

d(z) =< Ixl 


Overflow occurs 


SS$_ROPRAND 


MTH$_FLOOVEMAT 


Reserved operand. The MTH$xCOSH procedure 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 


Floating-point overflow in Math Library: the 
absolute value of x is greater than about yyy; 
LIBSSIGNAL copies the reserved operand to the 
signal mechanism vector. The result is the reserved 
operand -0.0 unless a condition handler changes 
the signal mechanism vector. 


The values of yyy are: 


MTH$C0SH 

MTHSDCOSH 

MTH$GC0SH 

MTHSHCOSH 


88.722 
88.722 
709.782 
1 1356.523 
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MTH$CxSIN—Complex Sine of Complex 



Number 

MTH$CxSIN returns the complex sine of a complex number (r,i). 

FORMAT 

MTH$CSIN complex-number 

MTH$CDSIN complex-sine ,complex-number 
MTH$CGSIN complex-sine ,complex-number 

Each of the above three formats accepts as input one of the three floating¬ 
point complex types. 

RETURNS 

VMS Usage: complex_number 
type: F_floating complex 

access: write only 

mechanism: by value 

Complex sine of the complex number. MTH$CSIN returns an F__floating 
complex number. MTH$CDSIN returns a D_floating complex number by 
reference in the complex-sine argument. MTH$CGSIN returns a G—floating 
complex number in the complex-sine argument. 

ARGUMENTS 

complex-number 

VMS Usage: complex_number 

type: F__floating complex, D_floating complex, G_floating 

complex 
access: read only 

mechanism: by reference 

A complex number (r,i), where r and i are floating-point numbers. The 
complex-number argument is the address of this complex number. For 
MTH$CSIN, complex-number specifies an F__floating complex number. For 
MTH$CDSIN, complex-number specifies a D_iloating complex number. For 
MTH$CGSIN, complex-number specifies a G_Jloating complex number. 

complex-sine 

VMS Usage: floating-point 
type: D_floating, G_floating 

access: write only 

mechanism: by reference 

Complex sine of the complex number. The complex sine routines with 
D_floating complex and G—floating complex input values write the address 
of the complex sine into this complex-sine argument. For MTH$CDSIN, 
complex-sine specifies a D_floating complex number. For MTH$CGSIN, 
complex-sine specifies a G__floating complex number. For MTH$CSIN, 
complex-sine is not used. 


DESCRIPTION The complex sine is computed as follows: 

complex-sine * (SIN(r) * COSH(i), COS(r) * SINH(i)) 
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CONDITION SS$_ROPRAND 

VALUES 

SIGNALED 


MTH$_FLOOVEMAT 


Reserved operand. The MTH$CxSIN procedure 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

Floating-point overflow in Math Library: the 
absolute value of i is greater than about 88.029 
for F_floating and D_floating values or greater than 
about 709.089 for G_floating values. 


EXAMPLE 

C+ 

C This FORTRAN example forms the complex 
C sine of a G_floating complex number using 
C MTH$CGSIN and the FORTRAN random number 

C generator RAN. 

C 

C Declare Z and MTH$CGSIN as complex values. 

C MTHICGSIN will return the sine value 
C of Z: CALL MTH$CGSIN(Z_NEW,Z) 

C- 

C0MPLEX*16 Z,Z_NEW 
COMPLEX*16 DCMPLX 
REAL*8 R,I 
INTEGER M 
M = 1234567 

C+ 

C Generate a random complex number with the 
C FORTRAN generic DCMPLX. 

C- 

R = RAN(M) 

I = RAN(M) 

Z = DCMPLX(R,I) 

C+ 

C Z is a complex number (r,i) with real part "r" and 
C imaginary part "i". 

C- 

TYPE *, 1 The complex number z is'.z 
TYPE *, ' ' 

C+ 

C Compute the complex sine value of Z. 

C- 

CALL MTHICGSIN(Z.NEW.Z) 

TYPE *, ' The complex sine value of'.z,' is',Z_NEW 
END 


This FORTRAN examples demonstrates a procedure call to MTH$CGSIN. 
Because this program uses G_floating numbers, it must be compiled with the 
statement "FORTRAN/G filename". 

The output generated by this program is as follows: 

The complex number z is (0.853540718555450,0.204340159893036) 

The complex sine value of (0.853540718555450,0.204340159893036) is 
(0.769400835484975,0.135253340912255) 
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MTH$CxSQRT—Complex Square Root 



MTH$CxSQRT returns the complex square root of a complex 
number (r,i). 

FORMAT 

MTH$CSQRT complex-number 

MTH$CDSQRT complex-sqrt ,complex-number 
MTH$CGSQRT complex-sqrt,complex-number 

Each of the above three formats accepts as input one of the three floating¬ 
point complex types. 

RETURNS 

VMS Usage: complex_number 
type: F_floating complex 

access: write only 

mechanism: by value 

The complex square root of complex-number. MTH$CSQRT returns an 
F_floating number. MTH$CDSQRT returns a D_floating complex number by 
reference in the complex-sqrt argument. MTH$CGSQRT returns a 

G_floating complex number in the complex-sqrt argument. 

ARGUMENTS 

complex-number 

VMS Usage: complex_number 

type: F_floating complex, D_floating complex, G_floating 

complex 
access: read only 

mechanism: by reference 

Complex number (r,i). The complex-number argument contains the address 
of this complex number. For MTH$CSQRT, complex-number specifies an 
F__floating number. For MTH$CDSQRT, complex-number specifies a 
D—floating number. For MTH$CGSQRT, complex-number specifies a 
G_floating number. 

complex-sqrt 

VMS Usage: complex_number 

type: D_floating complex, G-floating complex 

access: write only 

mechanism: by reference 

Complex square root of the complex number specified by complex-number. 
The complex square root routines that have D_lfloating complex and 
G_floating complex input values write the complex square root into 
complex-sqrt. For MTH$CDSQRT, complex-sqrt specifies a D_floating 
complex number. For MTH$CGSQRT, complex-sqrt specifies a G_floating 
complex number. For MTH$CSQRT, complex-sqrt is not used. 
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DESCRIPTION The complex square root is computed as follows. 

First, calculate ROOT and Q using the following equations: 

ROOT * SQRT((ABS(r) + (CABS((r,i)))/2) 

Q - 1/(2 * ROOT) 

Then, the complex result is given as follows: 


r 

i 

CSQRT((r,i)) 

>=0 

any 

(ROOT.Q) 

<0 

>=0 

(Q,ROOT) 

<0 

<0 

(-Q,-ROOT) 


CONDITION SSS—ROPRAND 

VALUE 

SIGNALED 


Reserved operand. The MTHSCxSQRT procedure 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 


EXAMPLE 

C+ 

C This FORTRAN example forms the complex square 
C root of a D_floating complex number using 
C MTH$CDSQRT and the FORTRAN random number 

C generator RAN. 

C 

C Declare Z and Z_NEW as complex values. MTH$CDSQRT 
C will return the complex square root of 
C Z: CALL MTH$CDSQRT(Z_NEW,Z). 

C- 

C0MPLEX*16 Z.Z.NEW 
COMPLEX*16 DCMPLX 
INTEGER M 
M = 1234567 

C+ 

C Generate a random complex number with the 
C FORTRAN generic CMPLX. 

C- 

Z = DCMPLX(RAN(M).RAN(M)) 

C+ 

C Z is a complex number (r.i) with real part "r" and imaginary 
C part "i". 

C- 

TYPE *, ' The complex number z is'.z 
TYPE *. ' ’ 

C+ 

C Compute the complex complex square root of Z. 

C- 

CALL MTH$CDSQRT(Z_NEW,Z) 

TYPE *, ' The complex square root of'.z,' is',Z_NEW 
END 
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This FORTRAN example program demonstrates a procedure call to 
MTH$CDSQRT. The output generated by this program is as follows: 

The complex number z is (0.8535407185554504,0.2043401598930359) 

The complex square root of (0.8535407185554504,0.2043401598930359) is 
(0.9303763973040062.0.1098158554350485) 
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MTH$CVT 

_x_x—Convert One Double- 
Precision Value 



MTH$CVT_D_G and MTH$CVT_G_D convert one double-precision 
value to the destination data type and return the result as a function 
value. MTH$CVT_D_G converts a D_floating value to G_floating 
and MTH$CVT_G_D converts a G_floating value to a D_floating 
value. 

• 

FORMAT 

MTH$CVT_D_G source 

MTH$CVT_G_D source 

• 

RETURNS 

VMS Usage: floating-point 
type: G—floating, D_floating 

access: write only 

mechanism: by value 

The converted value. MTH$CVT_D_G returns a G_floating value. 
MTH$CVT_G_D returns a D_floating value. 

• 

ARGUMENT 

source 

VMS Usage: floating-point 
type: D_floating, G_floating 

access: read only 

mechanism: by reference 

The input value to be converted. The source argument is the address of 
this input value. For MTH$CVT_D_G, the source argument specifies a 

D_floating number. For MTH$CVT_G_D, the source argument specifies a 
G_floating number. 


DESCRIPTION 

These procedures are designed to function like hardware conversion 
instructions. They fault on reserved operands. If floating-point overflow is 
detected, an error is signaled. If floating-point underflow is detected and 
floating-point underflow is enabled, an error is signaled. 

• 

CONDITION 

VALUES 

SIGNALED 

SS$_ROPRAND Reserved operand. The MTH$CVT_x_x procedure 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

MTH$_FLOOVEMAT Floating-point overflow in Math Library. 

MTH$_FLOUNDMAT Floating-point underflow in Math Library. 
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MTH$CVT_xA_xA—Convert an Array 



of Double-Precision 
Values 

MTH$CVT_DA_GA and MTH$CVT_GA_DA convert a contiguous 
array of double-precision values to the destination data type and 
return the results as an array. MTH$CVT_DA_GA converts D_ 
floating values to G_floating and MTH$CVT_GA_DA converts 
G_floating values to D_floating. 

FORMAT 

MTH$CVT_DA_GA source ,dest[,count] 
MTH$CVT_GA_DA source , dest[,count] 

RETURNS 

MTH$CVT_DA_GA and MTH$CVT—GA—DA return the address of the 
output array to the dest argument. 

ARGUMENTS 

source 

VMS Usage: floating-point 

type: D_floating, G_floating 

access: read only 

mechanism: by reference, array reference 

Input array of values to be converted. The source argument is the address of 
an array of floating-point numbers. For MTH$CVT_DA_GA, source specifies 
an array of D_floating numbers. For MTH$CVT_GA_DA, source specifies 
an array of a G_floating numbers. 

dest 

VMS Usage: floating-point 

type: G_floating, D_floating 

access: write only 

mechanism: by reference, array reference 

Output array of converted values. The dest argument is the address of an 
array of floating-point numbers. For MTH$CVT_DA_GA, dest specifies an 
array of G_floating numbers. For MTH$CVT_GA_DA, dest specifies an 
array of D_floating numbers. 

count 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Number of array elements to be converted. The default value is 1. The count 
argument is the address of this number of elements. 
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DESCRIPTION These procedures are designed to function like hardware conversion 

instructions. They fault on reserved operands. If floating-point overflow is 
detected, an error is signaled. If floating-point underflow is detected and 
floating-point underflow is enabled, an error is signaled. 


CONDITION SSS—ROPRAND 

VALUES 

SIGNALED 


MTH$_FLOOVEMAT 

MTH$_FLOUNDMAT 


Reserved operand. The MTH$CVT_xA_xA 
procedure encountered a floating-point reserved 
operand due to incorrect user input. A floating¬ 
point reserved operand is a floating-point datum 
with a sign bit of 1 and a biased exponent of zero. 
Floating-point reserved operands are reserved for 
future use by DIGITAL. 

Floating-point overflow in Math Library. 
Floating-point underflow in Math Library. 
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MTH$xEXP—Exponential 



MTH$xEXP returns the exponential of the input value. 

FORMAT 

MTHSEXP x 

MTHSDEXP x 

MTHSGEXP x 

MTHSHEXP h—exp ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$EXP_R4 

MTH$DEXP_R6 

MTH$GEXP_R6 

MTH$HEXP_R6 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

VMS Usage: floating-point 
type: F_floating, D_floating, G— floating 

access: write only 

mechanism: by value 

The exponential of x. MTH$EXP returns an F_floating number. MTH$DEXP 
returns a D_floating number. MTH$GEXP returns a G_floating number. 
Unlike the other three routines, MTH$HEXP returns the exponential by 
reference in the h_exp argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

The input value. The x argument is the address of a floating-point number. 
For MTH$EXP, x specifies an F_floating number. For MTH$DEXP, x specifies 
a D_floating number. For MTH$GEXP, x specifies a G_floating number. For 
MTH$HEXP, x specifies an H_floating number. 

h—exp 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Exponential of the input value specified by x. The h—exp argument is the 
address of an H_floating number that is this exponential. MTH$HEXP writes 
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the address of the exponential into h_exp. The h_exp argument is used only 
by the MTH$HEXP routine. 


DESCRIPTION The exponential of x is computed as: 


Value of x 

Value Returned 

x > c(z) 

Overflow occurs 

X <= -d(z) 

0 

Ixl < 

1 

Otherwise 

2 Y *2 U * 2 W 


where: 

Y = !NTEGER(x*ln2(E)) 

V = FRAC(x*ln2(E)) * 16 
U = INTEGERS)/16 

W = FRAC(V)/16 

2 W = polynomial approximation of degree 4,8,8,14 for z = F, D, G, or H. 

See also the section on the hyperbolic cosine for definitions of f, c(z), and d(z). 


CONDITION SS$_ROPRAND 

VALUES 

SIGNALED 


MTH$_FLOOVEMAT 


Reserved operand. The MTH$xEXP routine 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 


Floating-point overflow in Math Library: x is greater 
than yyy; LIBSSIGNAL copies the reserved operand 
to the signal mechanism vector. The result is the 
reserved operand -0.0 unless a condition handler 
changes the signal mechanism vector. The values 
of yyy are approximately: 


MTH$EXP 

MTH$DEXP 

MTHSGEXP 

MTHSHEXP 


88.029 
88.029 
709.089 
1 1355.830 
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MTH$_FLOUNDMAT 


Floating-point underflow in Math Library: x is 
less than or equal to yyy and the caller (CALL or 
JSB) has set hardware floating-point underflow 
enable. The result is set to 0.0. If the caller has 
not enabled floating-point underflow (the default), a 
result of 0.0 is returned but no error is signaled. 


The values of yyy are approximately: 
MTH$EXP -88.722 

MTH$DEXP -88.722 

MTHSGEXP -709.774 

MTHSHEXP -11356.523 


EXAMPLE 


IDENTIFICATION DIVISION. 

PROGRAM-ID. FLOATING.POINT. 

* 

* Calls MTH$EXP using a Floating Point data type. 

* Calls MTHtDEXP using a Double Floating Point data type. 

* 

ENVIRONMENT DIVISION. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

01 FLOAT.PT COMP-1. 

01 ANSWER.F COMP-1. 

01 DOUBLE.PT COMP-2. 

01 ANSWER.D COMP-2. 

PROCEDURE DIVISION. 

PO. 

MOVE 12.34 TO FLOAT.PT. 

MOVE 3.456 TO DOUBLE.PT. 

CALL "MTHSEXP" USING BY REFERENCE FLOAT.PT GIVING ANSWER.F. 
DISPLAY ■ MTHSEXP of ", FLOAT.PT CONVERSION, " is M , 

ANSWER.F CONVERSION. 


CALL "MTHSDEXP" USING BY REFERENCE DOUBLE.PT GIVING ANSWER.D. 
DISPLAY " MTHSDEXP of ", DOUBLE.PT CONVERSION, » is ", 

ANSWER.D CONVERSION . 


STOP RUN. 


This sample program demonstrates calls to MTH$EXP and MTH$DEXP from 
COBOL. 

The output generated by this program is as follows: 

MTH$EXP of 1.234000E+01 is 2.286620E+05 
MTHSDEXP of 3.456000000000000E+00 is 
3.168996280537917E+01 
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MTH$xlMAG—Imaginary Part of a 



Complex Number 

MTH$xlMAG returns the imaginary part of a complex number. 

FORMAT 

MTH$AIMAG complex-number 

MTH$DIMAG complex-number 

MTH$GIMAG complex-number 

Each of the above three formats corresponds to one of the three floating-point 
complex types. 

RETURNS 

VMS Usage: floating-point 

type: F—floating, D_floating, G_floating 

access: write only 

mechanism: by value 

Imaginary part of the input complex-number. MTH$AIMAG returns an 
F_floating number. MTH$DIMAG returns a D_floating number. 
MTH$GIMAG returns a G_floating number. 

ARGUMENT 

complex-number 

VMS Usage: complex-number 

type: F_floating complex, D_floating complex, G_floating 

complex 
access: read only 

mechanism: by reference 

The input complex number. The complex-number argument is the address 
of this floating-point complex number. For MTH$AIMAG, complex-number 
specifies an F_floating number. For MTH$DIMAG, complex-number 
specifies a D_floating number. For MTH$GIMAG, complex-number specifies 
a G_floating number. 

CONDITION 

VALUE 

SIGNALED 

SS$_ROPRAND Reserved operand. The MTH$xlMAG routine 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 


reserved operands are reserved for future use by 
DIGITAL. 
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EXAMPLE 

C+ 

C This FORTRAN example forms the imaginary part of 
C a G.floating complex number using MTHlGIMAG 
C and the FORTRAN random number generator 
C RAN. 

C 

C Declare Z as a complex value and MTH$GIMAG as 
C a REAL*8 value. MTH$GIMAG will return the imaginary 
C part of Z: Z.NEW = MTHlGIMAG(Z). 

C- 

C0MPLEX*16 Z 
COMPLEX*16 DCMPLX 
REAL*8 R.I,MTHlGIMAG 
INTEGER M 
M = 1234567 
C+ 

C Generate a random complex number with the 
C FORTRAN generic CMPLX. 

C- 

R = RAN(M) 

I = RAN(M) 

Z = DCMPLX(R,I) 

C+ 

C Z is a complex number (r,i) with real part "r" and 
C imaginary part "i". 

C- 

TYPE *, ' The complex number z is'.z 

TYPE *, 'It has imaginary part'.MTHlGIMAG(Z) 

END 


This FORTRAN example demonstrates a procedure call to MTH$GIMAG. 
Because this example uses G_-floating numbers, it must be compiled with the 
statement "FORTRAN/G filename". 

The output generated by this program is as follows: 

The complex number z is (0.8535407185554504,0.2043401598930359) 

It has imaginary part 0.2043401598930359 
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MTH$xLOG—Logarithm, Natural 



MTH$xLOG returns the natural (base e) logarithm of the input 
argument. 

FORMAT 

MTH$ALOG x 

MTH$DLOG x 

MTHSGLOG x 

MTH$HLOG h_natlog,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$ALOG_R5 

MTH$DLOG_R8 

MTH$GLOG_R8 

MTH$HLOG_R8 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating 

access: write only 

mechanism: by value 

The natural logarithm of x. MTH$ALOG returns an F_floating number. 
MTH$DLOG returns a D_floating number. MTH$GLOG returns a 

G_floating number. Unlike the other three routines, MTH$HLOG returns the 
natural logarithm by reference in the h_natlog argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

The input value. The x argument is the address of a floating-point number 
that is this value. For MTH$ALOG, x specifies an F_floating number. For 
MTH$DLOG, x specifies a D_floating number. For MTH$GLOG, x specifies 
a G_floating number. For MTH$HLOG, x specifies an H_floating number. 

h—natlog 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Natural logarithm of x. The h—natlog argument is the address of an 

H_floating number that is this natural logarithm. MTH$FiLOG writes the 
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address of this natural logarithm into h_natlog. The h__natlog argument is 
used only by the MTH$HLOG routine. 


DESCRIPTION Computation of the natural logarithm routine is based on the following: 

(1) ln(X*Y) = ln(X) + ln(Y) 

(2) ln(l+X) = X - X 2 /2 + X 3 /3 - X 4 /4 ... for |X| < 1 

(3) ln(X) * ln(A) + 2* (V + V 3 /3 + V 5 /5 + V 7 /7 ... ) 

= In(A) + V*p(V 2 ), where V = (X-A)/(X+A), 

A > 0, and p(y) ■ 2 * (1 ♦ y/3 + y 2 /5 ...) 

For x = 2 n *f, where n is an integer and t is in the 
interval of 0.5 to 1, define the following quantities: 

If n >= 1, then N = n-1 and F = 2f 
If n =< 0, then N = n and F = f 

From (1) above it follows that: 

(4) ln(X) = N*ln(2) + ln(F) 

Based on the above relationships, zLOG is computed as follows: 

(1) If IF-1I < 2 —5 , zLOG(X) = N*zL0G(2) + W + W*p(W). 

where W = F-l. 

(2) Otherwise. zLOG(X) = N*zL0G(2) + zLOG(A) + V*p(V 2 ), 

where V * (F-A)/(F+A) and A and zLOG(A) 
are obtained by table look up. 


CONDITION SS$_ROPRAND 

VALUES 

SIGNALED 


MTH$_LOGZERNEG 


Reserved operand. The MTH$xLOG procedure 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

Logarithm of zero or negative value: Argument x is 
less than or equal to 0.0. LIBSSIGNAL copies the 
floating-point reserved operand to the mechanism 

argument vector CHF$I_MCH_SAVR0/R1. The 

result is the floating-point reserved operand unless 
you have written a condition handler to change 
CHF$I_MCH_SAVR0/R1. 
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MTH$xLOG2—Logarithm, Base 2 



MTH$xLOG returns the base 2 logarithm of the input value specified 
by x. 

FORMAT 

MTH$ALOG2 x 

MTH$DLOG2 x 

MTH$GLOG2 x 

MTH$HLOG2 h_log2 ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

RETURNS 

VMS Usage: floating-point 

type: F_floating, D_floating, G—floating 

access: write only 

mechanism: by value 

The base 2 logarithm of x. MTH$ALOG2 returns an F_floating number. 
MTH$DLOG2 returns a D—floating number. MTH$GLOG2 returns a 
G_floating number. Unlike the other three routines, MTH$HLOG2 returns 
the base 2 logarithm by reference in the h_log2 argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D—floating, G_floating, H—floating 

access: read only 

mechanism: by reference 

The input value. The x argument is the address of a floating-point number 
that is this input value. For MTH$ALOG2, x specifies an F_floating number. 
For MTH$DLOG2, x specifies a D_floating number. For MTH$GLOG2, x 
specifies a G_floating number. For MTH$HLOG2, x specifies an H_floating 
number. 

h—log2 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Base 2 logarithm of x. The h_log2 argument is the address of an 

H_floating number that is this base 2 logarithm. MTH$HLOG2 writes the 
address of this logarithm into h—log2. The h—log2 argument is used only by 
the MTH$HLOG2 routine. 

DESCRIPTION 

The base 2 logarithm function is computed as follows: 

zLOG2(X) = zLOG2(E) * zLOG(X) 
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CONDITION 

VALUES 

SIGNALED 


SS$_ROPRAND Reserved operand. The MTH$xL0G2 procedure 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

MTH$_LOGZERNEG Logarithm of zero or negative value: Argument x is 

less than or equal to 0.0. LIBSSIGNAL copies the 
floating-point reserved operand to the mechanism 

argument vector CHF$I_MCH_SAVR0/R1. The 

result is the floating-point reserved operand unless 
you have written a condition handler to change 
CHF$I_MCH—SAVR0/R1. 


RTL-430 







Run-Time Library Routines 

MTH$xLOG10 


MTH$xLOG10—Logarithm, Common 



MTH$xLOG10 returns the common (base 10) logarithm of the input 
argument. 

FORMAT 

MTH$ALOG10 x 

MTHSDLOGIO x 

MTHSGLOGIO x 

MTH$HLOG10 h_log10,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$ALOG10_R5 

MTH$DLOG10_R8 

MTH$GLOG10_R8 

MTH$HLOG10_R8 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating 

access: write only 

mechanism: by value 

The common logarithm of x. MTH$ALOG10 returns an F_floating number. 
MTH$DLOG10 returns a D—floating number. MTH$GLOG10 returns a 

G_floating number. Unlike the other three routines, MTH$HLOG10 returns 
the common logarithm by reference in the h__loglO argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D—floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

The input value. The x argument is the address of a floating-point number. 
For MTH$ALOG10, x specifies an F_floating number. For MTH$DLOG10, x 
specifies a D—floating number. For MTH$GLOG10, x specifies a G_floating 
number. For MTH$HLOG10, x specifies an H_floating number. 

h—log 10 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Common logarithm of the input value specified by x. The h—loglO argument 
is the address of an H_floating number that is this common logarithm. 
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MTH$HLOG10 writes the address of the common logarithm into h_loglO. 
The h_loglO argument is used only by the MTH$HLOG10 routine. 

DESCRIPTION 

The common logarithm function is computed as follows: 

zLOG10(X) = zLOGlCXE) * zLOG(X) 

CONDITION 

VALUES 

SIGNALED 

SS$_ROPRAND Reserved operand. The MTH$xLOG10 procedure 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

MTH$_LOGZERNEG Logarithm of zero or negative value: Argument x is 

less than or equal to 0.0. LIBSSIGNAL copies the 


floating-point reserved operand to the mechanism 

argument vector CHF$l_MCH_SAVR0/R1. The 

result is the floating-point reserved operand unless 
you have written a condition handler to change 
CHF$L_MCH_S A VRO/R1. 
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MTH$RANDOM—Random-Number 

Generator, Uniformly 
Distributed 

MTH$RANDOM is a general random-number generator. 

FORMAT 

MTHSRANDOM seed 

RETURNS 

VMS Usage: floating-point 
type: F—floating 

access: write only 

mechanism: by value 

MTH$RANDOM returns an F_fioating random number. 

ARGUMENT 

seed 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

The integer seed, a 32-bit number whose high-order 24 bits are converted by 
MTH$RANDOM to an F_floating random number. The seed argument is the 
address of an unsigned longword that contains this integer seed. The seed is 
modified by each call to MTH$RANDOM. 

DESCRIPTION 

This routine must be called again to obtain the next pseudorandom number. 
The seed is updated automatically. 

The result is a floating-point number that is uniformly distributed between 

0.0 inclusively and 1.0 exclusively. 

There are no restrictions on the seed, although it should be initialized 
to different values on separate runs in order to obtain different random 
sequences. MTFl$RANDOM uses the following method to update the seed 
passed as the argument: 

SEED = (69069 * SEED + 1) (modulo 2 32 ) 


Reserved operand. The MTH$RANDOM procedure 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 


CONDITION SS$_ROPRAND 

VALUE 

SIGNALED 
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EXAMPLE 


RAND: PROCEDURE OPTIONS (MAIN); 

DECLARE FOR$SECNDS ENTRY (FLOAT BINARY (24)) 

RETURNS (FLOAT BINARY (24)); 

DECLARE MTH$RANDOM ENTRY (FIXED BINARY (31)) 

RETURNS (FLOAT BINARY (24)); 

DECLARE TIME FLOAT BINARY (24); 

DECLARE SEED FIXED BINARY (31); 

DECLARE I FIXED BINARY (7); 

DECLARE RESULT FIXED DECIMAL (2); 

/* Get floating random time value */ 

TIME = FORISECNDS (OEO); 

/* Convert to fixed */ 

SEED = TIME; 

/* Generate 100 random numbers between 1 and 10 */ 

DO I = 1 TO 100; 

RESULT = 1 + FIXED ( (10E0 * MTH$RANDOM (SEED) ),31 ); 
PUT LIST (RESULT); 

END; 

END RAND; 


7 4 6 
4 4 2 
1 10 10 
6 2 3 

8 6 4 
12 2 
3 8 1 


This PL/I program demonstrates the use of MTH$RANDOM. The value 
returned by FOR$SECNDS is used as the seed for the random-number 
generator to insure a different sequence each time the program is run. The 
random value returned is scaled so as to represent values between 1 and 10. 

Because this program generates random numbers, the output generated will 
be different each time the program is executed. One example of the outut 
generated by this program is as follows: 
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MTH$xREAL—Real Part of a Complex 



Number 

MTH$xREAL returns the real part of a complex number. 

FORMAT 

MTH$REAL complex-number 

MTH$DREAL complex-number 

MTH$GREAL complex-number 

Each of the above three formats accepts as input one of the three floating¬ 
point complex types. 

RETURNS 

VMS Usage: floating-point 

type: F_ floating, D_ floating, G_floating 

access: write only 

mechanism: by value 

Real part of the complex number. MTH$REAL returns an F_floating number. 
MTH$DREAL returns a D_floating number. MTH$GREAL returns a 
G—floating number. 

ARGUMENT 

complex-number 

VMS Usage: complex—number 

type: F— floating complex, D_ floating complex, G—floating 

complex 
access: read only 

mechanism: by reference 

The complex number whose real part is returned by MTH$REAL. The 
complex-number argument is the address of this floating-point complex 
number. For MTH$REAL, complex-number is an F_floating complex 
number. For MTH$DREAL, complex-number is a D_floating complex 
number. For MTH$GREAL, complex-number is a G—floating complex 
number. 

CONDITION 

VALUE 

SIGNALED 

SS$_ROPRAND Reserved operand. The MTHSxREAL procedure 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 


reserved operands are reserved for future use by 
DIGITAL. 
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EXAMPLE 

C+ 

C This FORTRAN example forms the real 
C part of an F.floating complex number using 
C MTH$REAL and the FORTRAN random number 
C generator RAN. 

C 

C Declare Z as a complex value and MTH$REAL as a 

C REAL*4 value. MTH$REAL will return the real 

C part of Z: Z.NEW = MTH$REAL(Z). 

C- 

COMPLEX Z 
COMPLEX CMPLX 
REAL*4 MTHIREAL 
INTEGER M 
M = 1234567 
C+ 

C Generate a random complex number with the FORTRAN 
C generic CMPLX. 

C- 

Z * CMPLX(RAN(M).RAN(M)) 

C+ 

C Z is a complex number (r.i) with real part "r" and imaginary 
C part "i". 

C- 

TYPE *, ' The complex number z is'.z 
TYPE *, • It has real part',MTH$REAL(Z) 

END 


This FORTRAN example demonstrates the use of MTH$REAL. The output of 
this program is as follows: 

The complex number z is (0.8535407,0.2043402) 

It has real part 0.8535407 
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MTH$xSIIM—Sine of Angle Expressed in 



Radians 

MTH$xSIN returns the sine of a given angle (in radians). 

FORMAT 

MTHSSIN x 

MTHSDSIN x 

MTHSGSIN x 

MTHSHSIN hsine ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$SIN_R4 

MTH$DSIN_R7 

MTH$GSIN_R7 

MTH$HSIN_R5 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

VMS Usage: floating-point 

type: F_floating, D_floating, G—floating 

access: write only 

mechanism: by value 

Sine of the angle specified by x. MTH$SIN returns an F_floating number. 
MTH$DSIN returns a D_floating number. MTH$GSIN returns a G_floating 
number. Unlike the other three routines, MTH$HSIN returns the sine by 
reference in the h_sine argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G—floating, H_floating 

access: read only 

mechanism: by reference 

Angle (in radians). The x argument is the address of a floating-point number 
that is this angle. For MTH$SIN, x specifies an F_floating number. For 
MTH$DSIN, x specifies a D_floating number. For MTH$GSIN, x specifies a 
G_floating number. For MTH$HSIN, x specifies an H—floating number. 
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hsine 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

The sine of the angle specified by x. The h—sine argument is the address 
of an H_floating number that is this sine. MTH$HSIN writes the address of 
the sine into h__sine. The h—sine argument is used only by the MTH$HSIN 
routine. 

DESCRIPTION 

See the MTH$SINCOS routine for the algorithm which is used to compute 
this sine. 

CONDITION 

VALUE 

SIGNALED 

SS$_ROPRAND Reserved operand. The MTHSxSIN procedure 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 


reserved operands are reserved for future use by 
DIGITAL. 
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MTH$xSINCOS—Sine and Cosine of Angle 



Expressed in Radians 

MTH$xSINCOS returns the sine and the cosine of a given angle (in 
radians). 

FORMAT 

MTH$SINCOS x ,sine,cosine 

MTH$DSINCOS x,sine,cosine 

MTH$GSINCOS x ,sine ,cosine 

MTH$HSINCOS x ,sine,cosine 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$SI NCOS—R5 

MTH$DSINCOS_R7 

MTH$GSINCOS_R7 

MTH$HSINCOS_R7 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

MTH$SINCOS, MTH$DSINCOS, MTH$GSINCOS, and MTH$HSINCOS 
return the sine and cosine of the input angle by reference in the sine and 
cosine arguments. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

Angle (in radians) whose sine and cosine are to be returned. The x 
argument is the address of a floating-point number that is this angle. 

For MTH$SINCOS, x is an F_floating number. For MTH$DSINCOS, x is 
a D_floating number. For MTH$GSINCOS, x is a G_floating number. For 
MTH$HSINCOS, x is an H_floating number. 

sine 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: write only 

mechanism: by reference 

Sine of the angle specified by x. The sine argument is the address of a 
floating-point number. MTH$SINCOS writes an F_ floating number into sine. 
MTH$DSINCOS writes a D_floating number into sine. MTH$GSINCOS 
writes a G_floating number into sine. MTH$HSINCOS writes an H_floating 
number into sine. 
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cosine 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: write only 

mechanism: by reference 

Cosine of the angle specified by x. The cosine argument is the address 
of a floating-point number. MTH$SINCOS writes an F_floating number 
into cosine. MTH$DSINCOS writes a D_floating number into cosine. 
MTH$GSINCOS writes a G_floating number into cosine. MTH$HSINCOS 
writes an TLJIoating number into cosine. 


DESCRIPTION All routines with JSB entry points accept a single argument in R0:Rm, where 

m, which is defined below, is dependent on the data type. 


Data Type 

m 

F_floating 

0 

D_floating 

1 

G_floating 

1 

H_floating 

3 


In general, Run-Time Library routines with JSB entry points return one 
value in R0:Rm. The MTH$SINCOS routine returns two values, however. 
The sine of x is returned in R0:Rm and the cosine of x is returned in 
(R <m+l> :R <2*m+l> ). 

In radians, the computation of zSIN(X) and zCOS(X) is based on the following 
polynomial expansions: 

SIN(X) = X - X 3 /(3J) + X 5 /(5!) - X 7 /(7!) ... 

= X + X«P(X 2 ). where P(y) = y/(3!) + y 2 /(6!) + y 3 /(7!) ... 

COS(X) ■ 1 - X 2 /(2!) + x 4 / (4!) -X 6 /(6!) ... 

“ Q(X 2 ), where Q(y) = (1 - y/(2!) + y 2 /(4!) + y 3 /(6!) ...) 

(1) If IXI < 2 ( ~f/ 2 \ 

then zSIN(X) = X and zCOS(X) = 1 
(see the section on MTH$zC0SH for the definition of f) 

(2) If 2 =< |X| < PI/4 

then zSIN(X) * X + P(X 2 ) 
and zCOS(X) = Q(X 2 ) 

(3) If PI/4 =< IXI and X > 0, 

(a) Let J = INT(X/(PI/4)) and I = J modulo 8 

(b) If J is even, let Y = X - J* (PI/4) 

otherwise, let Y * (J+l)* (PI/4) - X 

With the above definitions, the following table relates zSIN(X) 
and zCOS(X) to zSIN(Y) and zCOS(Y): 
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CONDITION 

VALUE 

RETURNED 


Value of / 

zSIN(X) 

zCOS(X) 

0 

zSIN(Y) 

zCOS(Y) 

1 

zCOS(Y) 

zSIN(Y) 

2 

zCOS(Y) 

-zSIN(Y) 

3 

zSIN(Y) 

-zCOS(Y) 

4 

-zSIN(Y) 

-zCOS(Y) 

5 

-zCOS(Y) 

-zSIN(Y) 

6 

-zCOS(Y) 

zSIN(Y) 

7 

-zSIN(Y) 

zCOS(Y) 


(c) zSIN(Y) and zCOS(Y) are computed as follows: 
zSIN(Y) = Y + P(Y 2 ), 
and zCOS(Y) = Q(Y 2 ) 

(4) If PI/4 =< |X| and X < 0, 

then zSIN(X) = -zSIN(|X|) 
and zCOS(X) * zC0S(|X|) 


SS$_ROPRAND Reserved operand. The MTH$xSINCOS procedure 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 
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MTH$xSINCOSD—Sine and Cosine of 

Angle Expressed in 
Degrees 

MTH$xSINCOSD returns the sine and cosine of a given angle (in 
degrees). 

FORMAT 

MTH$SINCOSD x ,sine ,cosine 

MTH$DSINCOSD x ,sine,cosine 

MTH$GSINCOSD x ,sine,cosine 

MTH$HSINCOSD x ,sine,cosine 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$SINCOSD_R5 

MTH$DSINCOSD_R7 

MTH$GSINCOSD_R7 

MTH$HSINCOSD_R7 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

MTH$SINCOSD, MTH$DSINCOSD, MTH$GSINCOSD, and 
MTH$HSINCOSD return the sine and cosine of the input angle by reference 
in the sine and cosine arguments. 


ARGUMENTS x 


VMS Usage: 
type: 
access: 
mechanism: 


floating-point 

F_floating, D_floating, G_floating, H_floating 
read only 
by reference 


Angle (in degrees) whose sine and cosine are returned by MTH$xSINCOSD. 
The x argument is the address of a floating-point number that is this angle. 
For MTH$SINCOSD, x is an F_floating number. For MTH$DSINCOSD, x is 
a D_floating number. For MTH$GSINCOSD, x is a G—floating number. For 
MTH$HSINCOSD, x is an H_floating number. 


sine 

VMS Usage: floating-point 

type: F_floating, D_floating, G—floating, H_floating 

access: write only 

mechanism: by reference 

Sine of the angle specified by x. The sine argument is the address of 
a floating-point number. MTH$SINCOSD writes an F_floating number 
into sine. MTH$DSINCOSD writes a D_floating number into sine. 
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MTH$GSINCOSD writes a G_floating number into sine. MTH$HSINCOSD 
writes an H_floating number into sine. 

cosine 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H—floating 

access: write only 

mechanism: by reference 

Cosine of the angle specified by x. The cosine argument is the address 
of a floating-point number. MTH$SINCOSD writes an F_floating 
number into cosine. MTH$DSINCOSD writes a D_floating number 
into cosine. MTH$GSINCOSD writes a G—floating number into cosine. 
MTH$HSINCOSD writes an TLJloating number into cosine. 


DESCRIPTION All routines with JSB entry points accept a single argument in R0:Rm, where 

ra, which is defined below, is dependent on the data type. 


Data Type 

m 

F_floating 

0 

D_floating 

1 

G_floating 

1 

H floating 

3 


In general, Run-Time Library routines with JSB entry points return one 
value in R0:Rm. The MTH$SINCOSD routine returns two values, however. 
The sine of x is returned in R0:Rm and the cosine of x is returned in 
(R <m+l> :R <2*m+l> ). 

In degrees, the computation of zSIND(X) and zCOSD(X) is based on the 
following polynomial expansions: 

SIND(X) = (C*X) - (OX) 3 /(3!) + (C*X) 5 /(5!) - (C*X) 7 /(7!) ... 

= X/2 6 ♦ X*P(X 2 ), 

where P(y) = -y/(3!) + y 2 /(5!) - y 3 /(7!) ... 

COSD(X) = 1 - (OX) 2 /(2!) + (OX) 4 /(4!) -(C*X) 6 /(6!) 

= Q(X 2 ), where Q(y) = 1 - y/(2!) + y 2 /(4!) - y 3 /(6!) ... 
and C = PI/180 

1 If IXI < (180/PI)*2~ 2(e ^ and underflow signaling is enabled, underflow 
is signaled for zSIND(X) and zSINCOSD(X). See MTH$zCOSH for the 
definition of e. 

OTHERWISE: 

2 If IXI < ( 180 /PI)* 2 (-fW f then zSIND(X)= (PI/180)*X and zCOSD(X) = 1 . 
See MTH$zCOSH for the definition of /. 

3 If (180/PI)*2(~f / 2 * =< IXI < 45 then zSIND(X) = X/2 6 + P(X 2 ) and 
zCOSD(X) = Q(X 2 ) 

4 If 45 =< IXI and X > 0, 

a Let / — INT(X/(45)) and I = J modulo 8 
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CONDITION 

VALUES 

SIGNALED 


b If J is even, let Y = X - J*45 ; otherwise, let Y = (J+l)*45 - X . With the 
above definitions, the following table relates zSIND(X) and zCOSD(X) 
to zSIND(Y) and zCOSD(Y): 


Value of 1 

zSIND(X) 

zCOSD(X) 

0 

zSIND(Y) 

zCOSD(Y) 

1 

zCOSD(Y) 

zSIND(Y) 

2 

zCOSD(Y) 

-zSIND(Y) 

3 

zSIND(Y) 

-zCOSD(Y) 

4 

-zSIND(Y) 

-zCOSD(Y) 

5 

-zCOSD(Y) 

-zSIND(Y) 

6 

-zCOSD(Y) 

zSIND(Y) 

7 

-zSIND(Y) 

zCOSD(Y) 


c zSIND(Y) and zCOSD(Y) are computed as follows: 

zSIND(Y) = Y/2^ + P(Y 2 ) 
zCOSD(Y) = Q(Y 2 ) 

d If 45 =< IXI and X < 0 , then zSIND(X) . -zS!ND(\X\) and zCOSD(X) = 
zCOSDOX\) 


SS$_ROPRAND Reserved operand. The MTH$xSINCOSD procedure 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

MTH$_FLOUNDMAT Floating-point underflow in Math Library. The 

absolute value of the input angle is less than 
180/PI*2**-m (where m = 128 for F_floating and 
D—floating, 1,024 for G_floating, and 16,384 for 
H_floating). 
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MTH$xSIND—Sine of Angle Expressed in 



Degrees 

MTH$xSIND returns the sine of a given angle (in degrees). 

FORMAT 

MTH$SIND x 

MTH$DSIND x 

MTH$GSIND x 

MTH$HSIND hsine ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$SIND_R4 

MTH$DSIND_R7 

MTH$GSIND_R7 

MTH$HSIND_R5 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating 

access: write only 

mechanism: by value 

The sine of the angle. MTH$SIND returns an F_floating number. 
MTH$DSIND returns a D_floating number. MTH$GSIND returns a 

G_floating number. Unlike the other three routines, MTH$HSIND returns 
the angle by reference in the h—sine argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

Angle (in degrees). The x argument is the address of a floating-point number 
that is this angle. For MTH$SIND, x specifies an F_floating number. For 
MTH$DSIND, x specifies a D_floating number. For MTH$GSIND, x specifies 
a G_floating number. For MTH$HSIND, x specifies an H_floating number. 
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hsine 


VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Sine of the angle specified by x. The h_sine argument is the 
H_floating number that is this sine. MTH$HSIND writes the 
angle into h_sine. The h—sine argument is used only by the 
routine. 


address of an 
address of the 
MTH$HSIND 


DESCRIPTION See MTH$SINCOSD for the algorithm that is used to compute the sine. 


CONDITION SS$_ROPRAND 

VALUES 

SIGNALED 


MTH$_FLOUNDMAT 


Reserved operand. The MTHSSIND procedure 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased ecponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

Floating-point underflow in Math Library. The 
absolute value of the input angle is less than 
180/PI*2**-m (where m = 128 for F_floating and 
D_floating, 1,024 for G_floating, and 16,384 for 
H_floating). 
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MTH$xSINH—Hyperbolic Sine 



MTH$xSINH returns the hyperbolic sine of the input value specified 
by x. 

FORMAT 

MTHSSINH x 

MTHSDSINH x 

MTH$GSINH x 

MTH$HSINH hsinh ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

RETURNS 

VMS Usage: floating-point 

type: F_floating, D_floating, G—floating 

access: write only 

mechanism: by value 

The hyperbolic sine of x. MTH$SINH returns an F_floating number. 
MTH$DSINH returns a D_floating number. MTH$GSINH returns a 

G_floating number. However, unlike the other three routines, MTH$HSINH 
returns the hyperbolic sine by reference in the h_sinh argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G— floating, H_floating 

access: read only 

mechanism: by reference 

The input value. The x argument is the address of a floating-point number 
that is this value. For MTH$SINH, x specifies an F_floating number. For 
MTH$DSINH, x specifies a D_floating number. For MTH$GSINH, x specifies 
a G_floating number. For MTH$HSINH, x specifies an H_floating number. 

hsinh 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Hyperbolic sine of the input value specified by x. The h_sinh argument 

is the address of an H_floating number that is this hyperbolic sine. 
MTH$HSINH writes the address of the hyperbolic sine into h—sinh. 

The h_sinh argument is used only by the MTH$HSINH routine. 


RTL-447 







Run-Time Library Routines 

MTH$xSINH 


DESCRIPTION Computation of the hyperbolic sine function depends on the magnitude of 

the input argument. The range of the function is partitioned using four data 
type dependent constants: a(z), b(z), c(z), and d(z). The subscript z indicates 
the data type. The constants depend on the number of exponent bits (e) and 
the number of fraction bits (/) associated with the data type (z). 

The values of e and / are: 


z 

e 

f 

F 

8 

24 

D 

8 

56 

G 

11 

53 

H 

15 

113 


The values of the constants in terms of e and / are: 


Variable 

Value 

a(z) 

2<-//2> 

b(z) 

CEiUm[(f+l)/2*ln(2) ] for F,D, and G 


(f+l)/2*ln(2) for H 

c(z) 

(2<«-D ~')*ln(2) 

d(z) 

c(zhlnQ) 


Based on the above definitions, zSINH(X) is computed as follows: 


Value of x 


Value Returned 

IXI < a(z) 


X 

a(z) =< IXI < 

.25 

zSINH(X) is computed using a power series 



expansion in IXI 2 

.25 =< IXI < 

b(z) 

(zEXP(X) - zEXP(-X))/2 

< 3 - 

A 

s 

A 

c(z) 

SI GN(X)*zEXP( \X\)/2 

c(z)=< IXI < 

d(z) 

SIGN(X)*zEXP(\X 1 -ln(2)) 

? 

A 


Overflow occurs 
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CONDITION 

VALUES 

SIGNALED 


SS$_ROPRAND 


MTH$_FLOOVEMAT 


Reserved operand. The MTHSxSINH procedure 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 


Floating-point overflow in Math Library: the 
absolute value of x is greater than yyy. LIB$SIGNAL 
copies the floating-point reserved operand to the 
mechanism argument vector CFIF$L_MCFL_SAVRO 
/R1. The result is the floating-point reserved 
operand unless you have written a condition 
handler to change CHF$L_MCH_SAVR0/R1. The 
values of yyy are approximately: 


MTH$SINH 

MTHSDSINH 

MTH$GSINH 

MTH$HSINH 


88.722 

88.722 

709.782 

11356.523 
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MTH$xSQRT—Square Root 



MTH$xSQRT returns the square root of the input value x. 

FORMAT 

MTHSSQRT x 

MTHSDSQRT x 

MTH$GSQRT x 

MTH$HSQRT h_sqrt ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$SQRT_R3 

MTH$DSQRT_R5 

MTH$GSQRT_R5 

MTH$HSQRT_R8 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating 

access: write only 

mechanism: by value 

The square root of x. MTH$SQRT returns an F—floating number. 
MTH$DSQRT returns a D_floating number. MTH$GSQRT returns a 

G_floating number. Unlike the other three routines, MTH$HSQRT returns 
the square root in the h—sqrt argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G-floating, H_floating 

access: read only 

mechanism: by reference 

Input value. The x argument is the address of a floating-point number that 
contains this input value. For MTH$SQRT, x specifies an F—floating number. 
For MTH$DSQRT, x specifies a D_floating number. For MTH$GSQRT, x 
specifies a G_floating number. For MTH$HSQRT, an H—floating number. 

hsqrt 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Square root of the input value specified by x. The h— sqrt argument is the 
address of an H—floating number that is this square root. MTH$HSQRT 
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DESCRIPTION 


CONDITION 

VALUES 

SIGNALED 


writes the address of the square root into h_sqrt. The h__sqrt argument is 
used only by the MTH$HSQRT routine. 


The square root of X is computed as follows: 


If X < 0, an error is signaled. 
Let X = 2 K * F 


where: 

K is the exponential part of the floating-point data 
F is the fractional part of the floating-point data 


s even: 

5 (2*-P) , 


If K is eve 
X = 2 (r 
zSQRT(X) = 2^ * zSQRT(F), 
1/2 =< F < 1, where P = K/2 


F, 

,P - 


If K is odd: _ „ _ 

X * 2 (2 * P+1) * F = 2 (2 * P+2 ) * (F/2) , 
zSQRT(X) = 2 (P+1) * zSQRT(F/2), 

1/4 =< F/2 < 1/2, where p = (K-l)/2 
Let F' = A*F + B, when K is even: 

A = 0.453730314 (octal) 

B = 0.327226214 (octal) 

Let F' = A* + B, when K is odd: 

A = 0.650117146 (octal) 

B = 0.230170444 (octal) 

Let K' * P, when K is even 
Let K' = P+1, when K is odd 

Let Y[0] = * F' be a straight line approximation 

within the given interval using coefficients A and B which 
minimize the absolute error at the midpoint and endpoint. 
Starting with Y[0], n Newton-Raphson iterations are performed: 
Y [n+1] = 1/2 * (Y[n] + X/Y[n]) 

where n = 2, 3, 3, or 5 for z = F_floating, D_floating, 
G_floating, or H_floating respectively. 


SS$_ROPRAND Reserved operand. The MTH$xSQRT procedure 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

MTH$_SQUROONEG Square root of negative number. Argument x is 

less than 0.0. LIB$SIGNAL copies the floating-point 
reserved operand to the mechanism argument 

vector CHF$l_MCH_SAVR0/R1. The result is the 

floating-point reserved operand unless you have 
written a condition handler to change CHF$I— 
MCH_SAVR0/R 1. 
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MTH$xTAN 


MTH$xTAIM—Tangent of Angle Expressed 



in Radians 

MTH$xTAN returns the tangent of a given angle (in radians). 

FORMAT 

MTH$TAN x 

MTHSDTAN x 

MTHSGTAN x 

MTH$HTAN h_tan ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$TAN_R4 

MTH$DTAN_R7 

MTH$GTAN_R7 

MTH$HTAN_R5 

Each of the above four JSB entries accepts as mput one of the four floating¬ 
point types. 

RETURNS 

VMS Usage: floating-point 

type: F—floating, D_floating, G_floating 

access: write only 

mechanism: by reference 

The tangent of the angle specified by x. MTH$TAN returns an F_floating 
number. MTH$DTAN returns a D_floating number. MTH$GTAN returns a 
G_floating number. Unlike the other three routines, MTH$HTAN returns an 
H_floating number by reference in the h—tan argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: read only 

mechanism: by value 

The input angle (in radians). The x argument is the address of a floating-point 
number that is this angle. For MTH$TAN, x specifies an F_floating number. 
For MTH$DTAN, x specifies a D_floating number. For MTH$GTAN, x 
specifies a G_floating number. For MTH$FiTAN, x specifies an H_floating 
number. 
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MTH$xTAN 


h—tan 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Tangent of the angle specified by x. The h—tan argument is the address 
of an H_floating number that is this tangent. MTH$HTAN writes the 
address of the tangent into h—tan. The h—tan argument is used only by the 
MTH$HTAN routine. 


DESCRIPTION When the input argument is expressed in radians, the tangent function is 

computed as follows: 

1 If IXI < , then zTAN(X) = X (see the section on MTH$zCOSH for 

the definition of f) 

2 Otherwise, call MTH$zSINCOS to obtain zSIN(X) and zCOS(X); then 
a If zCOSQQ = 0 , signal overflow 

b Otherwise, zTAN(X) = zSIN(X)/zCOS(X) 


CONDITION SSS—ROPRAND 

VALUES 

SIGNALED 


MTH$_FLOOVEMAT 


Reserved operand. The MTH$xTAN procedure 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

Floating-point overflow in Math Library. 
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MTH$xTAND 


MTH$xTAND—Return Tangent of Angle 



Expressed in Degrees 

MTH$xTAND returns the tangent of a given angle (in degrees). 

FORMAT 

MTHSTAND x 

MTH$DTAND x 

MTH$GTAND x 

MTHSHTAND h-tan ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

jsb entries 

MTH$TAND_R4 

MTH$DTAND_R7 

MTH$GTAND_R7 

MTH$HTAND_R5 

Each of the above four JSB entries accepts as input one of the four floating¬ 
point types. 

RETURNS 

VMS Usage: floating-point 

type: F—floating, D_floating, G_floating 

access: write only 

mechanism: by value 

Tangent of the angle specified by x. MTH$TAND returns an F_floating 
number. MTH$DTAND returns a D_floating number. MTH$GTAND returns 
a G—floating number. Unlike the other three routines, MTH$HTAND returns 
the angle in the h—tan argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F—floating, D_floating, G—floating, H_floating 

access: read only 

mechanism: by reference 

The input angle (in degrees). The x argument is the address of a floating¬ 
point number which is this angle. For MTH$TAND, x specifies an 

F—floating number. For MTH$DTAND, x specifies a D_1floating number. 

For MTH$GTAND, x specifies a G_floating number. For MTH$HTAND, x 
specifies an H_floating number. 
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MTH$xTAND 



h—tan 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Tangent of the angle specified by x. The h_tan argument is the address 
of an H_floating number that is this tangent. MTH$HTAND writes the 
address of the tangent into h—tan. The h—tan argument is used only by the 
MTH$HTAN routine. 

DESCRIPTION 

When the input argument is expressed in degrees, the tangent function is 
computed as follows: 

1 If IXI < fI80/P7>2 (_2) and underflow signaling is enabled, underflow is 
signaled (see the section on MTH$zCOSH for the definition of e). 

2 Otherwise, if IXI < (180/PI)*2^-^ 2) , then zTAND(X) = (PI/180)*X . See 
the description of MTH$zCOSH for the definition of /. 

3 Otherwise, call MTH$zSINCOSD to obtain zSIND(X) and zCOSD(X). 

a Then, if zCOSD(X) = 0 , signal overflow 

b Else, zTANDfX) = zS!ND(X)/zCOSD(X) 

CONDITION 

VALUES 

SIGNALED 

SS$_ROPRAND Reserved operand. The MTHSxTAND procedure 

encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 

MTH$_FLOOVEMAT Floating-point overflow in Math Library. 
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MTH$xTANH 


MTH$xTAIMH—Compute the Hyperbolic 



Tangent 

MTH$xTANH returns the hyperbolic tangent of the input value. 

FORMAT 

MTHSTANH x 

MTHSDTANH x 

MTHSGTANH x 

MTH$HTANH h_tanh ,x 

Each of the above four formats accepts as input one of the four floating-point 
types. 

RETURNS 

VMS Usage: floating-point 
type: F_floating, D_floating, G_floating 

access: write only 

mechanism: by value 

The hyperbolic tangent of x. MTH$TANH returns an F_floating number. 
MTH$DTANH returns a D_floating number. MTH$GTANH returns a 
G_floating number. Unlike the other three routines, MTH$HTANH returns 
the hyperbolic tangent by reference in the h—tanh argument. 

ARGUMENTS 

X 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

The input value. The x argument is the address of a floating-point 
number that contains this input value. For MTH$TANH, x specifies an 

F_floating number. For MTH$DTANH, x specifies a D_floating number. 

For MTH$GTANH, x specifies a G_floating number. For MTH$HTANH, x 
specifies an H_floating number. 

h—tanh 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by reference 

Hyperbolic tangent of the value specified by x. The h—tanh argument 
is the address of a H_floating number that is this hyperbolic tangent. 
MTH$HTANH writes the address of the hyperbolic tangent into h—tanh. The 
h—tanh argument is used only by the MTH$TANH routine. 
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DESCRIPTION 


CONDITION 

VALUE 

SIGNALED 


For MTH$HTANH, the hyperbolic tangent of x is computed as follows: 


Value of x 

Hyperbolic Tangent Returned 

IXI =< 2-9 

X 

2~9 < IXI=< 0.25 

zSINHCX) / zCOSH(X) 

0.25 < IXI <h 

(zEXP(2*X) - 1) / (zEXP(2*X) + 1) 

h=< IXI 

sign(X) * 1 

where g = 12, 28, 26, or 56 and h = 10, 21, 20, or 40 for z = F__floating, 
D__floating, G_floating, or H_floating, respectively. 

For MTH$TANH, MTH$DTANH, and MTH$GTANH the hyperbolic tangent 
of x is computed as follows: 

Value of x 

Hyperbolic Tangent Returned 

Ixl =< 2**-g 

X 

2**-g < IXI =< 0.5 

xTANH(X) = X + X~3 * R(X'2), where R(X~2) is a 
rational function of X*2. 

0.5 < IXI < 1.0 

xTANHCX) = xTANH(xHI) + xTANH(xLO)*C/B 

where C=1 - xTANH(xHI)*xTANH(xHI), B = 1 + 
xTANH(xHI)*xTANH(xLO), xHI = l/2 + N/16 + 
1/32 for N=0,l,...,7, and xLO = X - xHI. 

1.0 < IXI < h 

xTANHCX) = (xEXP(2*X) - 1) / (xEXP(2*X) + 1) 

h=< IXI 

xTANH(X) = sign(X) * 1 

where g is as above and h = 

10, 20, 19 for F, D, G. 

SS$_ROPRAND 

Reserved operand. The MTHSxTANH procedure 
encountered a floating-point reserved operand due 
to incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
DIGITAL. 
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MTH$UMAX 


MTH$UMAX—Compute Unsigned 



Maximum 

MTH$UMAX computes the unsigned longword maximum of n 
unsigned longword arguments, where n is greater than or equal 
to 1. 

FORMAT 

MTH$UMAX argl [... ,argn] 

RETURNS 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Maximum value returned by MTH$UMAX. 

ARGUMENTS 

argl 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

First of the arguments of which MTH$UMAX computes the maximum. The 
argl argument is an unsigned longword which contains the first value. 

argn 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Last of the arguments of which MTH$UMAX computes the maximum. The 
argn argument is an unsigned longword which contains the last of the values 
which MTH$UMAX compares to find the maximum. 


DESCRIPTION MTH$UMIN is the unsigned version of MTH$JMAX0. 


CONDITION 

VALUES 

RETURNED 

None. 
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MTH$UMIN 


MTH$UMIN—Compute Unsigned Minimum 



MTH$UMIN computes the unsigned longword minimum of n 
unsigned longword arguments, where n is greater than or equal to 

1. 

FORMAT 

MTHSUMIN argl [... ,argn] 

RETURNS 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Minimum value returned by MTH$UMIN. 

ARGUMENTS 

argl 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

First of the arguments of which MTH$UMIN computes the minimum. The 
argl argument is an unsigned longword which contains the first value. 

argn 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Last of the arguments of which MTH$UMIN computes the minimum. The 
argn argument is an unsigned longword which contains the last of the values 
which MTH$UMIN compares to find the minimum. 

DESCRIPTION 

MTH$UMIN is the unsigned version of MTH$JMIN0. 

SHORT 

None. 
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OTS$CVT_l_TB 


OTS$CVT_l_TB—Convert an Unsigned 



Integer to Binary Text 

0TS$CVT_l_TB converts an unsigned integer value of arbitrary 

length to binary representation in an ASCII text string. By default, a 
longword is converted. 

FORMAT 

OTS$CVT_l_TB value, out-str [,int-digits] 

[, value-size] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

value 

VMS Usage: varying_arg 
type: unspecified 

access: read only 

mechanism: by reference 

Unsigned integer value that OTS$CVT_L_TB converts to binary 
representation in an ASCII text string. The value argument is the address of 
this integer value. 

out-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor, fixed-length 

ASCII text string that OTS$CVT_L_TB creates when it converts the integer 
value. The out-str argument is the address of a descriptor pointing to this 
ASCII text string. The string is assumed to be fixed length 
(DSC$K_CLASS_S). 

int-digits 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Minimum number of digits in the binary representation to be generated. The 
int-digits argument is a signed longword integer containing this minumum 
number. This is an optional argument. If omitted, the default is 1. If the 
actual number of significant digits is less than the minimum number of digits, 
leading zeros are produced. If the minimum number of digits is zero and the 
value of the integer to be converted is also zero, OTS$CVT_L_TB creates a 
blank string. 
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OTS$CVT_l_TB 


value-size 


VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Size of the integer to be converted, in bytes. The value-size argument is 
a signed longword integer containing the byte size. This is an optional 
argument. If omitted, the default is 4. 


CONDITION SS$_NORMAL 
VALUES OTSS—OUTCONERR 

RETURNED 


Routine successfully completed. 

Output conversion error. The result would have 
exceeded the fixed-length string; the output string 
is filled with asterisks. 


EXAMPLE 

0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

FTTY D F 4 TTY 

C* Initialize numeric value to be converted. 

C Z-ADD13 VALUE 90 

C CVTLTB EXTRN'0TS$CVT_L_TB' 

C* Convert the number to binary in a string. 

C CALL CVTLTB 

C PARM VALUE RL 

C PARMD 0UTSTR 4 

C* Display on the terminal the converted string. 

C OUTSTR DSPLYTTY 

C SETON LR 

The RPG II program above displays the string '1101' on the terminal. 
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OTS$CVT_l_Tl 


OTS$CVT_l_Tl—Convert Signed Integer 

to Decimal Text 

OTS$CVT_l_Tl converts a signed integer to a decimal ASCII text 

string. This procedure supports FORTRAN Iw and Iw.m output and 
BASIC output conversion. 


FORMAT 

OTS$CVT_l_Tl value, out-str [,int-digits] 

[, value-size] [, flags] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

value 

VMS Usage: varying_arg 
type: unspecified 

access: read only 

mechanism: by reference 

Signed integer value that OTS$CVT_L_TI converts to a decimal ASCII text 
string. The value argument is the address of this integer value. 


out-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor, fixed-length 

Decimal ASCII text string that OTS$CVT_L_TI creates when it converts the 
signed integer. The out-str argument is the address of a descriptor pointing to 
this text string. The string is assumed to be fixed length (DSC$K_CLASS_S). 


int-digits 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Minimum number of digits to be generated when OTS$CVT_L_TI converts 
the signed integer to a decimal ASCII text string. The int-digits argument 
is a signed longword integer containing this number. This is an optional 
argument. If omitted, the default value is 1. If the actual number of 
significant digits is smaller, OTS$CVT_L__TI inserts leading zeros into the 
output string. If int-digits is zero and value is zero, OTS$CVT_L_TI writes 
a blank string to the output string. 
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OTS$CVT_l_Tl 



value-size 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Number of bytes occupied by the value to be converted to text. The value- 
size argument is a signed longword integer containing this value size. The 
value size must be either 1, 2, or 4. If value size is 1 or 2, the value is 
sign-extended to a longword before conversion. This is an optional argument. 
If omitted, the default is 4. 

flags 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by value 

Caller-supplied flags that you may use if you want OTS$CVT_L_TI to insert 
a plus sign before the converted number. The flags argument is an unsigned 
longword containing the flags. 

The caller flags are defined as follows: 

Bit 0 If set, a plus sign ( + ) will be inserted before the first nonblank character 

in the output string; otherwise, the plus sign will be omitted. 

This is an optional argument. If flags is omitted, all bits are clear and the plus 
sign is not inserted. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Routine successfully completed. 

OTS$_OUTCONERR Output conversion error. The result would have 

exceeded the fixed-length string; the output string 
is filled with asterisks. 
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OTS$CVT_l_TL 


OTS$CVT_I_TL—Convert Integer to 



Logical Text 

OTS$CVT_l_TL converts an integer to ASCII text string 

representation using FORTRAN L (logical) format. 

FORMAT 

OTS$CVT_l_TL value ,out-str 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

value 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Value that OTS$CVT_L_TL converts to an ASCII text string. The value 
argument is the address of a signed longword integer containing this integer 
value. 

out-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor, fixed-length 

Output string that OTS$CVT_L_TL creates when it converts the integer 
value to an ASCII text string. The out-str argument is the address of a 
descriptor pointing to this ASCII text string. 

The output string is assumed to be fixed length (DSC$K_CLASS_S). 

The output string consists of (length -1) blanks followed by the letter T if bit 0 
is set, or the letter F if bit 0 is clear. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Routine successfully completed. 

OTS$_OUTCONERR Output conversion error. The result would have 

exceeded the fixed-length string; the output string 
is of zero length (DSC$W_LENGTH=0). 
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OTS$CVT_l_TL 


EXAMPLE 

5 ! + 

! This is an example program 
! showing the use of OTS$CVT_L_TL. 
! - 

VALUE*/. * 10 
0UTSTR$ = ' ' 

CALL OTS$CVT_L_TL(VALUE*/., 0UTSTR$) 
PRINT 0UTSTR$ 

9 END 


This BASIC example illustrates the use of OTS$CVT_L_TL. The output 
generated by this program is "F". 
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OTS$CVT_l_TO 


OTS$CVT_l_TO—Convert Unsigned 

Integer to Octal Text 

OTS$CVT_l_TO converts an unsigned integer to an octal ASCII 

text string. OTS$CVT_l_TO supports FORTRAN Ow and Ow.m 

output conversion formats. 


FORMAT 

OTS$CVT_l_TO value,out-str [,int-digits] 

[, value-size] 

RETURNS 

VMS Usage: 

cond_value 


type: 

longword (unsigned) 


access: 

write only 


mechanism: 

by value 


ARGUMENTS value 


VMS Usage: varying_arg 
type: unspecified 

access: read only 

mechanism: by reference 

Integer value that OTS$CVT_L_TO converts to an octal ASCII text string. 
The value argument is the address of this integer value. 


out-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor, fixed-length 

Output string that OTS$CVT_L_TO creates when it converts the integer 
value to an octal ASCII text string. The out-str argument is the address of a 
descriptor pointing to the octal ASCII text string. The string is assumed to be 
fixed length (DSC$K_CLASS_S). 


int-digits 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Minimum number of digits that OTS$CVT__L__TO generates when it converts 
the integer value to an octal ASCII text string. The int-digits argument is 
a signed longword integer containing the minimum number of digits. This 
is an optional argument. If omitted, the default is 1. If the actual number 
of significant digits in the octal ASCII text string is less than the minimum 
number of digits, OTS$CVT_L_TO inserts leading zeros into the output 
string. If int-digits is zero and value is zero, OTS$CVT_L_TO writes a 
blank string to the output string. 
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OTS$CVT_l_TO 



value-size 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Size of the integer to be converted, in bytes. The value-size argument is a 
signed longword integer containing the number of bytes in the integer to be 
converted by OTS$CVT_L_TO. This is an optional argument. If omitted, the 
default is 4. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Routine successfully completed. 

OTS$_OUTCONERR Output conversion error. The result would have 

exceeded the fixed-length string; the output string 
is filled with asterisks. 
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OTS$CVT_l_TU 


OTS$CVT__l_TU—Convert Unsigned 

Integer to Decimal Text 

OTS$CVT_J_TU converts a byte, word or longword value to 

unsigned decimal representation in an ASCII text string. By default, 
a longword is converted. 


FORMAT 

OTS$CVT_l_TU value ,out-str[,int-digits] 

[,value-size] 

RETURNS 

VMS Usage: 

cond_value 


type: 

longword (unsigned) 


access: 

write only 


mechanism: 

by value 


ARGUMENTS value 


VMS Usage: varying_arg 
type: unspecified 

access: read only 

mechanism: by reference 

Unsigned byte, word or longword that OTS$CVT_L_TU converts to 
unsigned decimal representation in an ASCII text string. (The value of the 
value-size argument determines whether value is a byte, word or longword.) 
The value argument is the address of the unsigned integer. 


out-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor, fixed-length 

Output string (fixed-length) that OTS$CVT_L_TU creates when it converts 
the integer value to unsigned decimal representation in an ASCII text string. 
The out-str argument is the address of a descriptor pointing to this ASCII text 
string. 


int-digits 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by value 

Minimum number of digits in the ASCII text string that OTS$CVT_L_TU 
creates. The int-digits argument is an unsigned longword containing the 
minimum number. This is an optional argument. If omitted, the default is 1. 

If the actual number of significant digits in the output string created is less 
than the minimum number, OTS$CVT_L_TU inserts leading zeros into the 
output string. If the minimum number of digits is zero and the integer value 
to be converted is also zero, OTS$CVT_L_TU writes a blank string to the 
output string. 
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OTS$CVT_l_TU 


value-size 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by value 


Size of the integer value to be converted, in bytes. The value-size argument 
is an unsigned longword containing the size of the integer value. This is 
an optional argument. If omitted, the default is 4. The only values that 
OTS$CVT_L__TU allows are 1, 2 and 4. If any other value is specified, 
OTS$CVT_L_TU uses the default value, 4. 


CONDITION SS$_NORMAL 

VALUES OTS$_OUTCONERR 

RETURNED 


Routine successfully completed. 

Output conversion error. The result would have 
exceeded the fixed-length string; the output string 
is filled with asterisks. 


EXAMPLE 


0|1|2I3|4|5|6|7I 
12346678901234567890123466789012346078901234667890123466789012346678901234667890 
FTTY D F 7 TTY 

C* Initialize numeric value to be converted. 

C Z-ADD32857 VALUE 90 

C Z-ADD7 DIGITS 90 

C CVTLTU EXTRN'OTS$CVT_L_TU' 

O Convert the number to decimal in a string with 7 decimal digits. 

C CALL CVTLTU 

C PARM VALUE RL 

C PARMD OUTSTR 7 

C PARMV DIGITS 

C* Display on the terminal the converted string. 

C OUTSTR DSPLYTTY 

C SETON LR 

The RPG II program above displays the string '003285 T on the terminal 
screen. 
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OTS$CVT_l_TZ—Convert Integer to 



Hexadecimal Text 

0TS$CVT_l_TZ converts an unsigned integer to a hexadecimal 

ASCII text string. OTSSCVT L TZ supports FORTRAN Zw and 
Zw.m output conversion formats. 

FORMAT 

OTS$CVT_I_TZ value, out-str [,int-digits] [, value- 

size] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

value 

VMS Usage: varying_arg 
type: unspecified 

access: read only 

mechanism: by reference 

Integer value that OTS$CVT_L_TZ converts to a hexadecimal ASCII text 
string. The value argument is the address of this integer value. 

out-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor, fixed-length 

Output string that OTS$CVT_L_TZ creates when it converts the integer 
value to a hexidecimal ASCII text string. The out-str argument is the address 
of a descriptor pointing to this ASCII text string. The string is assumed to be 
fixed length (DSC$K_CLASS_S). 

int-digits 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Minimum number of digits in the ASCII text string that OTS$CVT_L_TZ 
creates when it converts the integer. The int-digits argument is a signed 
longword integer containing this minimum number. This is an optional 
argument. If omitted, the default is 1. If the actual number of significant 
digits in the text string that OTS$CVT_L_TZ creates is less than this 
minimum number, OTS$CVT_L__TZ inserts leading zeros in the output 
string. If the minimum number of digits is zero and the integer value to be 
converted is also zero, OTS$CVT_L_TZ writes a blank string to the output 
string. 
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value-size 


VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Size of the integer that OTS$CVT_L_TZ converts, in bytes. The value-size 
argument is a signed longword integer containing the value size. This is an 
optional argument. If omitted, the default is 4. 


CONDITION SSS—NORMAL 

VALUES OTS$_OUTCONERR 

RETURNED 


Routine successfully completed. 

Output conversion error. The result would have 
exceeded the fixed-length string; the output string 
is filled with asterisks. 


EXAMPLE 


with TEXT.IO; use TEXT.IO; 
procedure SHOW.CONVERT is 

type INPUT.INT is new INTEGER range 0..INTEGER'LAST; 

INTVALUE : INPUT.INT := 256; 

HEXSTRING : STRING(1..11); 

procedure CONVERT.TO.HEX (I : in INPUT.INT; HS : out STRING); 

pragma INTERFACE (RTL. CONVERT.TO.HEX); 

pragma IMPORT.PROCEDURE (INTERNAL => CONVERT.TO.HEX. 

EXTERNAL => "OTS$CVT_L_TZ", 

MECHANISM =>(REFERENCE. 

DESCRIPTOR (CLASS => S))); 


begin 

CONVERT.TO.HEX (INTVALUE. HEXSTRING); 
PUT.LINECThis is the value of HEXSTRING") ; 
PUT.LINE(HEXSTRING); 
end; 


This Ada example uses OTS$CVT_L__TZ to convert a longword integer to 
hexadecimal text. 
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OTS$CNVOUT—Convert D_floating, 



G_floating or H_floating 
to Character String 

OTS$CNVOUT, OTS$CNVOUT_G and OTS$CNVOUT_H convert a 
D_floating ( G_floating or H_floating number to a character string in 
the FORTRAN E format. 

FORMAT 

OTS$CNVOUT value,out-string,digits-in-fract 
OTS$CNVOUT_G value ,out-string,digits-in-fract 
OTS$CNVOUT_H value ,out-string,digits-in-fract 

RETURNS 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

value 

VMS Usage: floating-point 

type: D_floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

Value that OTS$CNVOUT converts to a character string. For OTS$CNVOUT, 
the value argument is the address of a D_floating number containing the 
value. For OTS$CNVOUT_G, the value argument is the address of a 
G_floating number containing the value. For OTS$CNVOUT_H, the value 
argument is the address of an H_floating number containing the value. 

out-string 

VMS Usage: char—string 
type: character string 

access: write only 

mechanism: by descriptor, fixed length 

Output string into which OTS$CNVOUT writes the character string result 
of the conversion. The out-string argument is the address of a descriptor 
pointing to the output string. 

digits-in-fract 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by value 

Number of digits in the fractional portion of the result. The digits-in-fract 
argument is an unsigned longword containing the number of digits to be 
written to the fractional portion of the result. 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SS$_ROPRAND 

OTS$_OUTCONERR 


Routine successully completed. 

Floating reserved operand detected. 

Output conversion error. The result would have 
exceeded the fixed-length string; the output string 
is filled with asterisks. 
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OTS$CVT. 

_TB_L—Convert Binary Text to 
Unsigned Integer 


OTS$CVT_TB_L converts an ASCII text string representation of 
an unsigned binary value to an unsigned integer value of arbitrary 
length. By default, the result is a longword. Valid input characters 
are the blank and the digits 0 and 1. No sign is permitted. 

FORMAT 

OTS$CVT_TB_L inp-str, value [, value-size] [, flags] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

inp-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Input string containing the ASCII text string representation of an unsigned 
binary value that OTS$CVT_TB_L converts to an integer value. The inp-str 
argument is the address of a descriptor pointing to the ASCII text string. 


value 

VMS Usage: varying_arg 
type: unspecified 

access: write only 

mechanism: by reference 

Integer that OTS$CVT_TB_L creates when it converts the ASCII text string. 
The value argument is the address of the integer value. 


value-size 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Number of bytes occupied by the value created when OTS$CVT_TB_L 
converts the ASCII text string to an integer value. The value-size argument 
contains the value size. If value-size contains a zero or a negative number, 
OTS$CVT_TB_L returns an error code as the condition value. This is an 
optional argument. If omitted, the default is 4. 
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flags 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by value 

User-supplied flags that OTS$CVT_TB_L uses to determine how to interpret 
blanks and tabs. The flags argument contains the value of the user-supplied 
flags. 

The flags are defined as follows: 


Bit Description 

0 If set, OTS$CVT_TB_L ignores blanks. If clear, OTS$CVT_TB_L 

interprets blanks as zeros. 

4 If set, OTS$CVT_TB_L ignores tabs. If clear, OTS$CVT_TB_L 

interprets tabs as invalid characters. 


This is an optional argument. The default is that all bits are clear. 


CONDITION SS$_NORMAL 
VALUES OTS$_INPCONERR 

RETURNED 


Routine successfully completed. 

Input conversion error. An invalid character, 
overflow, or invalid value-size occurred. 


EXAMPLE 


1 

OPTION k 

TYPE = EXPLICIT 

! ♦ 

! This program demonstates the use of OTS$CVT_TB_L from BASIC. 
! Several binary numbers are read and then converted to their 
! integer equivalents. 


DECLARATIONS 


DECLARE STRING BIN.STR 
DECLARE LONG BIN.VAL, I, RET_STATUS 
DECLARE LONG CONSTANT FLAGS =17 ! 2~0 + 2~4 

EXTERNAL LONG FUNCTION OTS$CVT_TB_L (STRING. LONG, k 
LONG BY VALUE. LONG BY VALUE) 


MAIN PROGRAM 


Read the data, convert it to binary, and print the result. 


FOR I = 1 TO 5 
READ BIN.STR 

RET.STATUS = OTS$CVT_TB_L( BIN.STR. BIN.VAL, '4'L, FLAGS) 
PRINT BIN.STR;" treated as a binary number equals";BIN.VAL 
NEXT I 


Done, end the program. 


GOTO 32767 
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999 Data "1111", "1 111", "1011011", "11111111", "00000000" 
32767 END 


This BASIC example program demonstrates how to call OTS$CVT_TB_L to 
convert binary text to a longword integer. 

The output generated by this BASIC program is as follows: 

1111 treated as a binary number equals 15 
1 111 treated as a binary number equals 15 
1011011 treated as a binary number equals 91 
11111111 treated as a binary number equals 255 
00000000 treated as a binary number equals 0 
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OTS$CVT_TI_L—Convert Signed Integer 



Text to Integer 

OTS$CVT_TI_L converts an ASCII text string representation of a 
decimal number to a signed byte, word, or longword integer value. 
The result is a longword by default, but the calling program can 
specify a byte or a word value instead. 

FORMAT 

OTS$CVT_TI _L inp-str, value [, value-size] [, flags] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

inp-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor, fixed-length or dynamic string 

Input ACSII text string that OTS$CVT_TI_L converts to a signed byte, word, 
or longword. The inp-str argument is the address of a descriptor pointing to 
the input string. 

The syntax of a valid ASCII text input string is as follows: 

[+ or -] <integer-digit8> 

OTS$CVT_TI_L always ignores leading blanks. A decimal point is assumed 
at the right of the input string. 

value 

VMS Usage: varying_arg 
type: unspecified 

access: write only 

mechanism: by reference 

Signed byte, word, or longword integer value (depending on value-size) that 
OTS$CVT_TI_L creates when it converts the ASCII text string. The value 
argument is the address of the integer value. 

value-size 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Number of bytes occupied by the value that OTS$CVT_TI_L creates when it 
converts the ASCII text string to an integer value. Valid values for the value- 
size argument are 1, 2, and 4. The contents of value-size determine whether 
the integer value that OTS$CVT_TI_L creates is a byte, word, or longword. 

If an invalid value is given, OTS$CVT_TI_L returns an error. This is an 
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optional argument. If omitted, the default is 4 and OTS$CVT_TI_L returns a 
longword integer. 


flags 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by value 

User-supplied flags that OTS$CVT_TI_L uses to determine how blanks and 
tabs are interpreted. The flags argument is an unsigned longword containing 
the value of the flags. 


Bit Description 

0 If set, OTS$CVT_TI_L ignores all blanks. If clear, OTS$CVT_TI_L 

ignores leading blanks but interprets blanks after the first legal character 
as zeros. 

4 If set, OTS$CVT_TI_L ignores tabs. If clear, OTS$CVT_TI_L interprets 

tabs as invalid characters. 


This is an optional argument. If omitted, the default is that all bits are cleared 
and OTS$CVT_TI_L ignores blanks and tabs. 


CONDITION SS$_NORMAL 
VALUES OTS$_INPCONERR 

RETURNED 


Routine successfully completed. 

Input conversion error; an invalid character in the 
input string, or the value overflows byte, word, or 
longword, or value-size is invalid; value is set to 
zero. 
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OTS$CVT_TI_L—Convert Logical Text to 

Integer 

OTS$CVT_TI_L converts an ASCII text string representation of a 

FORTRAN-77 L format to a byte, word, or longword integer value. 
The result is a longword by default, but the calling program can 
specify a byte or a word value instead. 


FORMAT OTS$CVT_TI_L inp-str, value [, value-size] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


ARGUMENTS 


inp-str 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 

by descriptor, fixed-length or dynamic string 

Input string containing an ASCII text representation of a FORTRAN-77 L 
format that OTS$CVT_TL_L converts to a byte, word or longword integer 
value. The inp-str argument is the address of a descriptor pointing to the 
input string. 

The syntax of a valid ASCII text input string is as follows: 

<zero or more blanks> 

< <end of string> 
or 

< or nothing> 

Letter: <"T", "t", "F", or "f H > 

<zero or more of any character> 

<end of string»> 


value 

VMS Usage: varying_arg 
type: unspecified 

access: write only 

mechanism: by reference 

Integer value that OTS$CVT_TL_L creates when it converts the ACSII 
text input string. The value argument is the address of this integer value. 
OTS$CVT_TL_L returns a minus one (-1) as the contents of the value 
argument if the character denoted by "Letter:" is "T" or "t". Otherwise, 
OTS$CVT_TL_L sets value to zero. 
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value-size 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Number of bytes occupied by the integer value that OTS$CVT_TL_L creates 
when it converts the ASCII text input string. The value-size argument 
contains the number of bytes. Valid values are 1, 2, and 4. These values 
determine whether OTS$CVT_TL__L returns a byte, word or longword 
integer value. If an invalid value is given, OTS$CVT_TL__L returns an error. 
This is an optional argument. If omitted, the default is 4 and OTS$CVT_TL_ 
L returns a longword integer value. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Routine successfully completed. 

OTS$_INPCONERR Invalid character in the input string or invalid 

value-size; value is set to zero. 
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OTS$CVT_TO_L—Convert Octal Text to 

Signed Integer 

OTS$CVT_TO_L converts an ASCII text string representation of an 
unsigned octal value to an unsigned integer of an arbitrary length. 
The result is a longword by default, but the calling program can 
specify any number of bytes. 


FORMAT 

OTS$CVT_T 0_L inp-str, value [, value-size] [, flags] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

inp-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor, fixed-length or dynamic string 

Input string containing an ASCII text string representation of an unsigned 
octal value that OTS$CVT_TO_L converts to an unsigned integer. The 
inp-str argument is the address of a descriptor pointing to the input string. 
The valid input characters are blanks and the digits 0 through 7. No sign is 
permitted. 


value 

VMS Usage: varying—arg 
type: unspecified 

access: write only 

mechanism: by reference 

Integer value that OTS$CVT_TO_L creates when it converts the input string. 
The value argument is the address of the unsigned integer value. 


value-size 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Number of bytes occupied by the unsigned integer value. The value-size 
argument contains the number of bytes. If the content of the value-size 
argument is zero or a negative number, OTS$CVT_TO—L returns an error. 
This is an optional argument. If omitted, the default is 4 and OTS$CVT—TO— 
L returns a longword integer. 
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flags 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by value 

User-supplied flags that OTS$CVT_TO_L uses to determine how blanks 
within the input string are interpreted. The flags argument contains the 
user-supplied flags. 

Bit 0 If set, OTS$CVT_TO_L ignores all blanks. If clear, OTS$CVT_TO_L 
interprets blanks as zeros. 

This is an optional argument. If omitted, the default is that all bits are clear. 


CONDITION SS$_NORMAL 

VALUES OTS$_INPCONERR 

RETURNED 


Routine successfully completed. 

Input conversion error. An invalid character, 
overflow, or invalid value-size occurred. 


EXAMPLE 


OCTAL.CONV: PROCEDURE OPTIONS (MAIN) RETURNS (FIXED BINARY (31)); 

^INCLUDE $STSDEF; /* Include definition of return status values */ 

DECLARE 0TS$CVT_T0_L ENTRY 

(CHARACTER (*), /* Input string passed by descriptor */ 

FIXED BINARY (31), /* Returned value passed by reference */ 

FIXED BINARY VALUE, /* Size for returned value passed by value */ 

FIXED BINARY VALUE) /* Flags passed by value */ 

RETURNS (FIXED BINARY (31)) /* Return status */ 

OPTIONS (VARIABLE); /* Arguments may be omitted */ 

DECLARE INPUT CHARACTER (10); 

DECLARE VALUE FIXED BINARY (31); 

DECLARE SIZE FIXED BINARY(31) INITIAL(4) READONLY STATIC; /* Longword */ 

DECLARE FLAGS FIXED BINARY(31) INITIAL(l) READONLY STATIC; /* Ignore blanks */ 
ON ENDFILE (SYSIN) STOP; 

DO WHILE Cl'B); /* Loop continuously, until end of file */ 


PUT SKIP (2); 

GET LIST (INPUT) OPTIONS (PROMPT ('Octal value: ')); 
STS$VALUE * 0TS$CVT_T0_L (INPUT, VALUE, SIZE, FLAGS); 

IF ~STS$SUCCESS THEN RETURN (STS$VALUE); 

PUT SKIP EDIT (INPUT. 'Octal equals', VALUE, 'Decimal') 
(A,X,A,X,F(10),X,A); 

END; 

END OCTAL.CONV; 


This PL/I program translates an octal value in ASCII into a fixed binary 
value. The program is run interactively; simply type CTRL/Z to quit. 

$ RUN OCTOL 
Octal value: 1 

I Octal equals 1 Decimal 
Octal value: 11 

II Octal equals 9 Decimal 
Octal value: 1017346 

1017346 Octal equals 274150 Decimal 
Octal value: CTRL/Z 
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OTS$CVT_TU_L—Convert Unsigned 



Decimal Text to Integer 

OTS$CVT_TU_L converts an ASCII text string representation of 
an unsigned decimal value to an unsigned byte, word, or longword 
value. By default, the result is a longword. Valid input characters 
are the space and the digits 0 through 9. No sign is permitted. 

FORMAT 

OTS$CVT_TU_L inp-str , value [, value-size] [, flags] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

inp-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor, fixed-length 

Input string (fixed-length) containing an ASCII text string representation of an 
unsigned decimal value that OTS$CVT_TU_L converts to a byte, word, or 
longword value. The inp-str argument is the address of a descriptor pointing 
to the input string. 

value 

VMS Usage: varying_arg 
type: unspecified 

access: write only 

mechanism: by reference 

Byte, word, or longword (depending on value-size) into which OTS$CVT_ 
TU_L writes the converted value. The value argument is the address of the 
byte, word, or longword. 

value-size 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Number of bytes occupied by the value created when OTS$CVT_TU_L 
converts the input string. The value-size argument contains the number of 
bytes. OTS$CVT_TU—L allows value sizes of 1, 2 and 4. If any other value 
is specified, or if value-size is omitted, OTS$CVT_TU_ L uses the default, 4. 
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flags 


VMS Usage: 
type: 


mask—longword 
longword (unsigned) 
read only 


access: 


mechanism: by value 

User-supplied flags which OTS$CVT_TU_L uses to determine how blanks 
and tabs are interpreted. The flags argument contains the user-supplied flags. 


Bit Description 

0 If set, OTS$CVT_TU_L ignores blanks. If clear, OTS$CVT_TU_L interprets 
blanks as zeros. 

4 If set, OTS$CVT_TU_L ignores tabs. If clear, OTS$CVT_TU_L interprets 
tabs as invalid characters. 


Flags is an optional argument. If omitted, the default is that all bits are clear. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

OTS$_INPCONERR 


Routine successfully completed. 

Input conversion error. An invalid character, 
overflow or invalid value-size occurred. 
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OTS$CVT_T_z — Convert Numeric Text to 

Floating 


The OTS$CVT_T_z routines convert an ASCII text string 
representation of a numeric value to a D_floating, F_floating, 
G_floating, or H_floating value. 

FORMAT 

OTS$CVT_T_D inp-str, value [, digits-in-fract] 

[, scale-factor] [, flags] [, ext-bits] 
OTS$CVT_T_F inp-str, value [, digits-in-fract] 

[, scale-factor] [, flags] [, ext-bits] 
OTS$CVT_T_G inp-str, value [, digits-in-fract] 

[, scale-factor] [, flags] [, ext-bits] 
OTS$CVT_T_H inp-str, value [, digits-in-fract] 

[, scale-factor] [, flags] [, ext-bits] 

Each of the above four formats corresponds to one of the four floating-point 
types. 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 


inp-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor, fixed-length or dynamic string 

Input string containing an ASCII text string representation of a numeric value 
that OTS$CVT_T_Z converts to a D_floating, F_floating, G-floating, or H- 
floating value. The inp-str argument is the address of a descriptor pointing to 
the input string. 


The syntax of a valid input string is as follows: 


<zero or more blanks> 
or nothing> 

<zero or more decimal digits> 

" or nothing> 

<zero or more decimal digits> 

<exponent or nothing, where exponent is: 

< «"E", "e", "D", "d", "Q" , or "q"> 

<zero or more blanks> 

or nothing» 
or 

or 

<zero or more decimal digits» 

<end o t string> 
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There is no difference in semantics among any of the six valid exponent 
letters (E, e, D, d, Q, q). 


value 

VMS Usage: floating-point 

type: D—floating, F_floating, G_floating, H_floating 

access: write only 

mechanism: by reference 

Floating-point value that OTS$CVT_T_z creates when it converts the input 
string. The value argument is the address of the floating-point value. For 
OTS$CVT_T—D, value is a D_floating number. For OTS$CVT_T_F, value is 
an F—floating number. For OTS$CVT_T_G, value is a G—floating number. 
For OTS$CVT_T_FI, value is an IT—floating number. 


digits-in-fract 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by value 

Number of digits in the fraction if no decimal point is included in the input 
string. The digits-in-fract argument contains the number of digits. This is an 
optional argument. If omitted, the default is zero. 


scale-factor 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Scale factor. The scale-factor argument contains the value of the scale factor. 
If bit 6 of the flags argument is clear, the resultant value is divided by 10 f actor 
unless the exponent is present. If bit 6 of flags is set, the scale factor is always 
applied. This is an optional argument. If omitted, the default is zero. 


flags 

VMS Usage: 

type: 

access: 

mechanism: 

User-supplied 


mask—longword 
longword (unsigned) 
read only 
by value 

flags. The flags argument contains the user-supplied flags. 


Bit 0 If set, OTS$CVT_T_z ignores blanks. If clear, OTS$CVT_T_z interprets 
blanks as zeros. 

Bit 1 If set, OTS$CVT_T_z allows only E or e exponents. If clear, OTS$CVT_ 
T_z allows E, e, D, d, Q and q exponents. (Bit 1 is clear for BASIC and 
set for FORTRAN.) 

Bit 2 If set, OTS$CVT_T_z interprets an underflow as an error. If clear, 
OTS$CVT_T_z does not interpret an underflow as an error. 

Bit 3 If set, OTS$CVT_T_z truncates the value. If clear, OTS$CVT_T-z 
rounds the value. 

Bit 4 If set, OTS$CVT_T_z ignores tabs. If clear, OTS$CVT_T_z interprets 
tabs as invalid characters. 
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Bit 5 If set, an exponent must begin with a valid exponent letter. If clear, the 
exponent letter may be omitted. 

Bit 6 If set, OTS$CVT_T_z always applies the scale factor. If clear, 

OTS$CVT_T_z applies the scale factor only if there is no exponent 
present in the string. 

If flags is omitted, all bits are clear. 


ext-bits 

VMS Usage: word_signed 
type: word integer (signed) 

access: write only 

mechanism: by reference 

Extra precision bits. The ext-bits argument is the address of a signed word 
integer containing the extra precision bits. If present, value is not rounded, 
and the first n bits after truncation are returned in this argument. For D_ 
floating and F_floating, n equals 8 and the bits are returned as a byte. For 
G_floating and H_floating, n equals 11 and 15, respectively, and the bits are 
returned as a word, left-justified. 


These values are suitable for use as the extension operand in an EMOD 
instruction. 


The extra precision bits returned for H—floating may not be precise because 
calculations are only carried to 128 bits. However, the error should be small. 


DESCRIPTION These routines support FORTRAN D, E, F, and G input type conversion as 

well as similar types for other languages. 

OTS$CVT_T_D, OTS$CVT_T_F, OTS$CVT_T_G, and OTS$CVT_T_H 
provide run-time support for BASIC and FORTRAN input statements. 


CONDITION SSS—NORMAL 

VALUES OTS$_INPCONERR 

RETURNED 


Routine successfully completed. 

Input conversion error; an invalid character in the 
input string, or the value is outside the range that 
can be represented. Value is set to +0.0 (not 
reserved operand -0.0). 


EXAMPLE 


c+ 

C This is a FORTRAN program demonstrating the use of 
C 0TS$CVT_T_F. 

C- 

REAL*4 A 

CHARACTER*10 T(5) 

DATA T/'1234567+23','8.786534+3',•-983476E-3',’-23.734532'.•45'/ 
DO 2 I * 1. 5 
TYPE l.I.T(I) 

1 FORMAT(' Input string ',11,' is ',A10) 

C+ 

C B is the return status. 

C T(I) is the string to be converted to an 
C F_floating point value. A is the F_floating 
C point conversion of T(I). 7,VAL(5) means 5 digits 

C are in the fraction if no decimal point is in 
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C the input string T(I). 

C- 

B = OTS$CVT_T_F(T(I) , A,‘/.VAL(5) , , ) 

TYPE Output of OTSCVT.T.F is ',A 

TYPE *,' ' 

2 CONTINUE 

END 


This FORTRAN example demonstrates the use of OTS$CVT_T_F. The output 
generated by this program is as follows: 


Input string 1 is 1234567+23 
Output of 0TSCVT_T_F is 
Input string 2 is 8.786534+3 
Output of 0TSCVT_T_F is 
Input string 3 is -983476E-3 
Output of 0TSCVT_T_F is 
Input string 4 is -23.734532 
Output of OTSCVT.T.F is 

Input string 5 is 45 
Output of OTSCVT.T.F is 


1.2345669E+24 
8786.534 
-9.8347599E-03 
-23.73453 
45000.00 
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OTS$CVT_TZ_L—Convert Hexadecimal 

Text to Unsigned 
Integer 

OTS$CVT_TZ_L converts an ASCII text string representation of an 
unsigned hexadecimal value to an unsigned integer of an arbitrary 
length. The result is a longword by default, but the calling program 
can specify either 1, 2 or 4 bytes to receive either a byte, word, or 
longword value. 


FORMAT 

OTS$CVT_TZ_L inp-str, value [, value-size][, flags] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

inp-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor, fixed-length or dynamic string 

Input string containing an ASCII text string representation of an unsigned 
hexadecimal value that OTS$CVT_TZ_L converts to an unsigned integer. 

The inp-str argument is the address of a descriptor pointing to the input 
string. Valid input characters are the space, the digits 0 through 9, and the 
letters A through F. No sign is permitted. Lowercase letters a through f are 
acceptable. 


value 

VMS Usage: varying—arg 
type: unspecified 

access: write only 

mechanism: by reference 

Integer value created when OTS$CVT_TZ_L converts the input string. The 
value argument is the address of the integer value. 


value-size 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Number of bytes occupied by the integer value. The value-size argument 
contains the number of bytes. If the value size is zero or a negative number, 
OTS$CVT_TZ_L returns an input conversion error. This is an optional 
argument. If omitted, the default is 4. 
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flags 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by value 

User-supplied flags that OTS$CVT_TZ_L uses to determine how blanks are 
interpreted. The flags argument is an unsigned longword containing these 
user-supplied flags. 

Bit 0 If set, OTS$CVT_TZ_L ignores blanks. If set, OTS$CVT_TZ_L 
interprets blanks as zeros. 

This is an optional argument. If omitted, the default is that all bits are clear. 


CONDITION SS$_NORMAL 

VALUES OTS$_INPCONERR 

RETURNED 


Routine successfully completed. 

Input conversion error. An invalid character, 
overflow, or invalid value-size occurred. 


EXAMPLES 


10 


100 


This BASIC program converts a character string representing 
a hexadecimal value to a longword. 


Illustrate (and test) OTS convert hex-string to longword 


EXTERNAL LONG FUNCTION OTS$CVT_TZ_L 
EXTERNAL LONG CONSTANT 0TS$_INPC0NERR 
INPUT "Enter hex numeric";HEXVAL$ 

RET.STAT7. = OTS$CVT_TZ_L (HEXVAL$, HEX'/. ) 

PRINT -Conversion error " IF RET.STATy, * 0TS$_INPC0NERR 
PRINT -Decimal value of ";HEXVAL$;" is";HEX'/. k 

IF RET.STATY. <> 0TS$_INPC0NERR 


This BASIC example accepts a hexadecimal numeric string, converts it to a 
decimal integer, and prints the result. One sample of the output generated by 
this program is as follows: 

$ RUN HEX 

Enter hex numeric? A 
Decimal value of A is 10 


E HEX.CONV: PROCEDURE OPTIONS (MAIN) RETURNS (FIXED BINARY (31)); 

y,INCLUDE ISTSDEF; /* Include definition of return status values */ 

DECLARE OTS$CVT_TZ_L ENTRY 

(CHARACTER (*), /* Input string passed by descriptor */ 

FIXED BINARY (31), /* Returned value passed by reference */ 

FIXED BINARY VALUE, /* Size for returned value passed by value */ 

FIXED BINARY VALUE) /* Flags passed by value */ 

RETURNS (FIXED BINARY (31)) /* Return status */ 

OPTIONS (VARIABLE); /* Arguments may be omitted */ 

DECLARE INPUT CHARACTER (10); 

DECLARE VALUE FIXED BINARY (31); 


DECLARE FLAGS FIXED BINARY(31) INITIAL(l) READONLY STATIC; /* Ignore blanks */ 
ON ENDFILE (SYSIN) STOP; 

DO WHILE (•1•B); /* Loop continuously, until end of file */ 

PUT SKIP (2); 

GET LIST (INPUT) OPTIONS (PROMPT ('Hex value: ')); 
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STS$VALUE = OTS$CVT_TZ_L (INPUT. VALUE. . FLAGS); 

IF “STSISUCCESS THEN RETURN (STS$VALUE); 

PUT SKIP EDIT (INPUT, 'Hex equals', VALUE. 'Decimal') 


END; 

END HEX.CONV; 

(A.X,A,X,F(10).X,A); 


This PL/I example translates a hexadecimal value in ASCII into a fixed binary 
value. This program continues to prompt for input values until the user types 
CTRL/Z. 

One sample of the output generated by this program is as follows: 

$ RUN HEX 

Hex value: 1A 

1A Hex equals 26 Decimal 

Hex value: C 

C Hex equals 12 Decimal 

Hex value: CTRL/Z 
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OTS$DIVCx—Complex Division 

OTS$DIVC, 0TS$DIVCD_R3 and 0TS$DIVCG_R3 return a complex 



result of a complex division on complex numbers. 

FORMAT 

OTS$DIVC dividend,divisor 

OTS$DIVCD_R3 dividend,divisor 

OTS$DIVCG_R3 dividend,divisor 

Each of the above three formats corresponds to one of the three floating-point 
complex types. 

RETURNS 

VMS Usage: complex_number 
type: F_floating complex 

access: write only 

mechanism: by value 

Complex result of complex division. OTS$DIVC returns an F-floating 
number. OTS$DIVCD__R3 returns a D—floating number. OTS$DIVCG—R3 
returns a G_floating number. 

ARGUMENTS 

dividend 

VMS Usage: complex_number 

type: F-floating complex, D_floating complex, G— floating 

complex 
access: read only 

mechanism: by value 

Complex dividend. The dividend argument contains a floating-point 
complex value. For OTS$DIVC, dividend is an F—floating complex number. 
For OTS$DIVCD_R3, dividend is a D_Hoating complex number. For 
OTS$DIVCG—R3, dividend is a G_floating complex number. 

divisor 

VMS Usage: complex_number 

type: F_floating complex, D_floating complex, G_ floating 

complex 
access: read only 

mechanism: by value 

Complex divisor. The divisor argument contains the value of the divisor. For 
OTS$DIVC, divisor is an F_floating complex number. For OTS$DIVCD_R3, 
divisor is a D—floating complex number. For OTS$DIVCG__R3, divisor is a 
G—floating complex number. 
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DESCRIPTION These procedures return a complex result of a complex division on complex 

numbers. 

The complex result is computed as follows: 

1 Let (a,b) represent the complex dividend. 

2 Let (c,d) represent the complex divisor. 

3 Let (r,i) represent the complex quotient. 

The results of this computation are as follows: 

r = (ac + bd)/(cc + dd) 
i = (be - ad)/(cc + dd) 


CONDITION SS$_FLTDIV_F Arithmetic fault. Floating-point division by zero. 

VALUES SS$_FLTOV_F Arithmetic fault. Floating-point overflow. 

SIGNALED 

EXAMPLES 


C This FORTRAN example forms the complex 
C quotient of two complex numbers using 
C OTSlDIVC and the FORTRAN random number 

C generator RAN. 

C 

C Declare Zl, Z2, Z_Q, and 0TS$DIVC as complex values. 

C 0TS$DIVC will return the complex quotient of Zl divided 

C by Z2: Z_Q = 0TS$DIVC( %VAL(REAL(Z1)), */.VAL(AIMAG(Zl) , 

C y.VAL(REAL(Z2)), %VAL(AIMAG(Z2)) 

C- 

COMPLEX Zl,Z2,Z_q.0TS$DIVC 
C+ 

C Generate a complex number. 

C- 

Z1 = (8.0,4.0) 

C+ 

C Generate another complex number. 

C- 

Z2 = (1.0,1.0) 

C+ 

C Compute the complex quotient of Z1/Z2. 

C- 

Z_Q = 0TS$DIVC( y,VAL(REAL(Zl)) . y,VAL(AIMAG(Zl)) . %VAL(REAL(Z2)). 
+ '/.VAL(AIMAG(Z2))) 

TYPE *, ' The complex quotient of'.Zl,' divided by ',Z2,' is:' 

TYPE *, ' ',Z_Q 

END 


This FORTRAN program demonstrates how to call OTS$DIVC. The output 
generated by this program is as follows: 

The complex quotient of (8.000000,4.000000) divided by (1.000000,1.000000) is 
( 6 . 000000 ,- 2 . 000000 ) 
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C This FORTRAN example forms the complex 

C quotient of two complex numbers by using 
C 0TS$DIVCG_R3 and the FORTRAN random number 
C generator RAN. 

C 

C Declare Z1, Z2, and Z_Q as complex values. 0TS$DIVCG_R3 

C will return the complex quotient of Z1 divided by Z2: 

C Z_Q = Z1/Z2 
C- 

C0MPLEX*16 Z1,Z2,Z_Q 
O 

C Generate a complex number. 

C- 

Z1 = (8.0,4.0) 

C+ 

C Generate another complex number. 

C- 

Z2 = (1.0,1.0) 

C+ 

C Compute the complex quotient of Z1/Z2. 

C- 

Z_Q = Z1/Z2 

TYPE *, ' The complex quotient of'.Zl,' divided by ',Z2,' is:' 

TYPE *, ' ',Z_Q 

END 


This FORTRAN example uses the OTS$DIVCG_R3 entry point instead. 
Notice the difference in the precision of the output generated: 

The complex quotient of (8.000000000000000,4.000000000000000) divided by 
(1.000000000000000.1.000000000000000) is: 

(6.000000000000000,-2.000000000000000) 
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OTS$DIV_ 

-PK—LONG—Packed Decimal 

Division with Long 
Divisor 

OTS$DIV_PK_LONG divides fixed-point decimal data, which 
is stored in packed decimal form, when precision and scale 
requirements for the quotient call for multiple precision division. 

The divisor must have a precision of thirty or thirty-one digits. 

FORMAT 

OTS$DIV_PK_LONG divd ,divr ,divr-prec ,quot 

,quot-prec ,prec-data,scale- 
data 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

divd 

VMS Usage: address 
type: packed decimal string 

access: read only 

mechanism: by reference 

Dividend. The divd argument is the address of a packed decimal string which 
contains the shifted dividend. 

The divd argument is always multiplied by (10**c) prior to passing it as 
input, where c is defined as follows: 

c = 31 - prec(divd) 

Mutiplying divd by (10**c) makes divd a 31 digit number. 

divr 

VMS Usage: address 
type: packed decimal string 

access: read only 

mechanism: by reference 

Divisor. The divr argument is the address of a packed decimal string which 
contains the divisor. 

divr-prec 

VMS Usage: word_signed 
type: word integer (signed) 

access: read only 

mechanism: by value 

Precision of the divisor. The divr-prec argument is a signed word integer 
which contains the precision of the divisor. The high order bits are filled with 
zeros. 
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quot 

VMS Usage: address 
type: packed decimal string 

access: write only 

mechanism: by reference 

Quotient. The quot argument is the address of the packed decimal string into 
which OTS$DIV_PK_LONG writes the quotient. 

quot-prec 

VMS Usage: word_signed 
type: word integer (signed) 

access: read only 

mechanism: by value 

Precision of the quotient. The quot-prec argument is a signed word integer 
that contains the precision of the quotient. The high order bits are filled with 
zeros. 


prec-data 

VMS Usage: word_signed 
type: word integer (signed) 

access: read only 

mechanism: by value 

Additional digits of precision required. The prec-data argument is a signed 
word integer that contains the value of the additional digits of precision 
required. 

OTS$DIV_PK_LONG computes the prec-data argument as follows: 


proc-data = scale (quot) + scale (divr) - scale (divd) 
prec (divd) 


31 


scale-data 

VMS Usage: word-signed 
type: word integer (signed) 

access: read only 

mechanism: by value 

The scale-data argument is a signed word integer that contains the scale data. 
OTS$DIV_PK_LONG defines the scale-data argument as follows: 

scala-data = 31 - prec (divr) 


DESCRIPTION Before using this procedure, you should determine whether it would be best 

to use OTS$DIV_PK_LONG, OTS$DIV_PK_SHORT, or the VAX instruction 
DIVP. To determine this, you must first calculate b, where b is defined as 
follows: 

b = scale (quot) ♦ scale (divr) - scale (divd) + 
prec (divd) 

If b is greater than 31, then OTS$DIV_PK_LONG may be used to perform 
the division. If b is less that 31, you could use the instruction DIVP instead. 

Once you have determined that you cannot use DIVP, you need to determine 
whether you shuld use OTS$DIV_PK_LONG or OTS$DIV_PK_SHORT. 

To determine this, you must examine the value of scale-data. If scale-data 
is less than or equal to 1, then you should use OTS$DIV_PK_LONG. If 
scale-data is greater than 1, you should use OTS$DIV_PK_SHORT instead. 
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CONDITION SS$_FLTDIV Fatal error. Division by zero. 

VALUE 

SIGNALED 


EXAMPLE 

1 

OPTION 

TYPE = EXPLICIT 


k 


This program uses OTS$DIV_PK_LONG to perform packed decimal 
arithmetic. 


! DECLARATIONS 

DECLARE DECIMAL (31. 2) NATIONAL.DEBT 

DECLARE DECIMAL (30, 3) POPULATION 

DECLARE DECIMAL (10, 5) PER.CAPITA.DEBT 

EXTERNAL SUB 0TS$DIY_PK_L0NG (DECIMAL(31.2). DECIMAL (30, 3). k 
WORD BY VALUE. DECIMAL(10, 5), WORD BY VALUE, WORD BY VALUE, k 
WORD BY VALUE) 

! + 

! Prompt the user for the required input. 

INPUT "Enter national debt: NATIONAL.DEBT 

INPUT "Enter current population: ";POPULATION 

! ♦ 

! Perform the division and print the result. 

I 

! scale(divd) = 2 

! scale(divr) = 3 

! scale(quot) = 5 

! 

! prec(divd) - 31 

! prec(divr) * 30 

! prec(quot) = 10 

j 

! prec-data = scale(quot) + scale(divr) - scale(divd) - 31 + 

! prec(divd) 

! prec-data = 5 + 3 - 2 -31+31 

! prec-data = 6 

i 

• b = scale(quot) + scale(divr) - scale(divd) + prec(divd) 

! b = 5 + 3 - 2 + 31 

! b = 37 

! 

! c = 31 - prec(divd) 

! c = 31 - 31 

! c = 0 

j 

! scale-data = 31 - prec(divr) 

! scale-data = 31 - 30 

! scale-data = 1 

i 

! b is greater than 31, so either 0TS$DIV_PK_L0NG or 
! 0TS$DIV_PK_SH0RT may be used to perform the division. 

! If b is less than or equal to 31, then the DIVP 

! instruction may be used. 

i 

! scale-data is less than or equal to 1, so 0TS$DIV_PK_L0NG 
! should be used instead of 0TS$DIV_PK_SH0RT. 


/ 


f 
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I 


CALL 0TS$DIV_PK_L0NG( NATIONAL.DEBT, POPULATION. '30'W, PER_CAPITA_DEBT, & 
•10'W, '6'W, ’1'W) 

PRINT "The per capita debt is: ";PER_CAPITA_DEBT 
END 


This BASIC example program uses OTS$DIV_PK_LONG to perform packed 
decimal division. One example of the output generated by this program is as 
follows: 

$ RUN DEBT 

Enter national debt: ? 12345678 

Enter current population: ? 1212 

The per capita debt is: 10186.20297 
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OTS$DIV_ 

JPK—SHORT—Packed Decimal 

Division with 

Short Divisor 

OTS$DIV_PK_SHORT divides fixed-point decimal data, which 
is stored in packed decimal form, when precision and scale 
requirements for the quotient call for multiple-precision division. 

The divisor can have a maximum precision of twenty-nine digits. 

FORMAT 

OTS$DIV_PK_SHORT divd,divr,divr-prec,quot 

,quot-prec ,prec-data 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

divd 

VMS Usage: address 
type: packed decimal string 

access: read only 

mechanism: by reference 

Dividend.The divd argument is the address of a packed decimal string which 
contains the shifted dividend. 

The divd argument is always multiplied by (10**c) prior to passing it as 
input, where c is defined as: 

c = 31 - prec(divd) 

Multiplying divd by (10**c) makes divd a 31 digit number. 

divr 

VMS Usage: address 
type: packed decimal string 

access: read only 

mechanism: by reference 

Divisor. The divr argument is the address of a packed decimal string which 
contains the divisor. 
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divr-prec 

VMS Usage: word-signed 
type: word integer (signed) 

access: read only 

mechanism: by value 

Precision of the divisor. The divr-prec argument is a signed word integer 
which contains the precision of the divisor. The high-order bits are filled with 
zeros. 

quot 

VMS Usage: address 
type: packed decimal string 

access: write only 

mechanism: by reference 

Quotient. The quot argument is the address of a packed decimal string into 
which OTS$DIV_PK_SHORT writes the quotient. 

quot-prec 

VMS Usage: word—signed 
type: word integer (signed) 

access: read only 

mechanism: by value 

Precision of the quotient. The quot-prec argument is a signed word integer 
which contains the precision of the quotient. The high-order bits are filled 
with zeros. 


prec-data 

VMS Usage: word—signed 
type: word integer (signed) 

access: read only 

mechanism: by value 

Additional digits of precision required. The prec-data argument is a signed 
word integer which contains the value of the additional digits of precision 
required. 

OTS$DIV—PK—SHORT computes the prec-data argument as follows: 

pr«c-data = scale(quot) + scale(divr) - scale(divd) - 31 ♦ 
prec(divd) 


DESCRIPTION Before using this procedure, you should determine whether it would be best 

to use OTS$DIV_PK_LONG, OTS$DIV-PK-SHORT, or the VAX instruction 
DIVP. To determine this, you must first calculate b, where b is defined as 
follows: 

b * scale(quot) + scale(divr) - scale(divd) + prec(divd) 

If b is greater than 31, then OTS$DIV_PK_SHORT may be used to perform 
the division. If b is less that 31, you could use the VAX instruction DIVP 
instead. 

Once you have determined that you cannot use DIVP, you need to determine 
whether you should use OTS$DIV_PK_LONG or OTS$DIV_PK-SHORT. 

To determine this, you must examine the value of scale-data. If scale-data 
is less than or equal to 1, then you should use OTS$DIV—PK_LONG. If 
scale-data is greater than 1, you should use OTS$DIV_PK_SHORT instead. 
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CONDITION SS$_FLTDIV Fatal error. Division by zero. 

VALUE 

SIGNALED 
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OTS$MOVE3 - Move Data Without Fill 

0TS$M0VE3 moves up to 2**31-1 bytes, (2,147,483,647 bytes) 



from a specified source address to a specified destination address. 

FORMAT 

OTS$MOVE3 length,source ,dest 

corresponding 
jsb entry point 

OTS$MOVE3_R5 

RETURNS 

None. 

ARGUMENTS 

length 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Number of bytes of data to move. The length argument contains the number 
of bytes to move. The value of length may range from 0 to 2,147,483,647 
bytes. 

source 

VMS Usage: byte_unsigned 

type: byte (unsigned) 

access: read only 

mechanism: by reference, array reference 

Data to be moved by OTS$MOVE3. The source argument contains the 
address of an unsigned byte array that contains this data. 

dest 

VMS Usage: byte_unsigned 

type: byte (unsigned) 

access: write only 

mechanism: by reference, array reference 

Item into which source will be moved. The dest argument is the address of 
an unsigned byte array into which OTS$MOVE3 writes the source data. 


DESCRIPTION OTS$MOVE3 performs the same function as the VAX MOVC3 instruction 
except that the length is a longword integer rather than a word integer. 
When called from the JSB entry point, the register outputs of OTS$MOVE3__ 
R5 follow the same pattern as those of the MOVC3 instruction: 
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RO 0 

R1 Address of one byte beyond the source string 

R2 0 

R3 Address of one byte beyond the destination string 

R4 0 

R5 0 

For more information, see the description of the MOVC3 instruction in the 
VAX-11 Architecture Reference Manual See also the routine LIB$MOVC3, 
which is a callable version of the MOVC3 instruction. 


CONDITION 

VALUES 

RETURNED 


None. 
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OTS$MOVE5—Move Data with Fill 

0TS$M0VE5 moves up to 2**31-1 bytes, (2,147,483,647 bytes) 



from a specified source address to a specified destination address, 
with separate source and destination lengths, and with fill. Overlap 
of the source and destination arrays does not affect the result. 

FORMAT 

OTS$MOVE5 srclen ,source ,fill,dstlen ,dest 

corresponding 
jsb entry point 

OTS$MOVE5_R5 

RETURNS 

None. 

ARGUMENTS 

srclen 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Number of bytes of data to move. The srclen argument contains a signed 
longword integer that is this number. The value of srclen may range from 0 
to 2,147,483,647. 

source 

VMS Usage: byte_unsigned 

type: byte (unsigned) 

access: read only 

mechanism: by reference, array reference 

Data to be moved by OTS$MOVE5. The source argument contains the 
address of an unsigned byte array that contains this data. 

fill 

VMS Usage: byte—unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by value 

Character used to pad the source data if scrclen is less than dstlen. The fill 
argument contains the address of an unsigned byte that is this character. 

dstlen 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Size of the destination area in bytes. The dstlen argument is a signed 
longword integer containing this size. The value of dstlen may range from 0 
through 2,147,483,647. 
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dest 

VMS Usage: byte_unsigned 

type: byte (unsigned) 

access: write only 

mechanism: by reference, array reference 

Item into which source will be moved. The dest argument is the address of 
an unsigned byte array into which OTS$MOVE5 will write the source data. 

DESCRIPTION 

OTS$MOVE5 performs the same function as the VAX MOVC5 instruction 
except that the srclen and dstlen arguments are longword integers rather 
than word integers. When called from the JSB entry point, the register 
outputs of OTS$MOVE5__R5 follow the same pattern as those of the MOVC5 
instruction: 

RO Number of unmoved bytes remaining in source string 

R1 Address of one byte beyond the source string 

R2 0 

R3 Address of one byte beyond the destination string 

R4 0 

R5 0 

For more information, see the description of the MOVC5 instruction in the 
VAX-11 Architecture Reference Manual. See also the routine LIB$MOVC5, 
which is a callable version of the MOVC5 instruction. 

CONDITION 

VALUES 

RETURNED 

None. 
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OTS$MULCx—Complex Multiplication 

0TS$MULCD_R3 and 0TS$MULCG_R3 calculate the complex 
product of two complex values. 


FORMAT OTS$MULCD_R3 multiplier,multiplicand 

OTS$MULCG_R3 multiplier multiplicand 

The above formats correspond to the D_floating and G_floating complex 
types. 


RETURNS VMS Usage: complex—number 

type: D_floating complex, G-floating complex 

access: write only 

mechanism: by value 

Complex result of multiplying two complex numbers. OTS$MULCD_R3 
returns a D_floating complex number. OTS$MULCG—R3 returns a G— 
floating complex number. 


ARGUMENTS multiplier 

VMS Usage: complex—number 

type: D_floating complex, G-floating complex 

access: read only 

mechanism: by value 

Complex multiplier. The multiplier argument contains the multiplier. 

For OTS$MULCD—R3, multiplier is a D_floating complex number. For 
OTS$MULCG—R3, multiplier is a G—floating complex number. 

multiplicand 

VMS Usage: complex—number 

type: D_floating complex, G_floating complex 

access: read only 

mechanism: by value 

Complex multiplicand. The multiplicand argument contains the 
multiplicand. For OTS$MULCD_ R3, multiplicand is a D_floating complex 
number. For OTS$MULCG_ R3, multiplicand is an F—floating complex 
number. 


DESCRIPTION OTS$MULCD—R3 and OTS$MULCG_R3 calculate the complex product of 
two complex values. 

The complex product is computed as follows: 

1 Let (a,b) represent the complex multiplier. 

2 Let (c,d) represent the complex multiplicand. 

3 Let (r,i) represent the complex product. 
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The results of this computation are as follows: 

r = ac - bd 
i = ad + be 


CONDITION MTH$_FLOOVEMAT 

VALUES SSS—ROPRAND 

SIGNALED 


Floating-point overflow in Math Library. 

Reserved operand. OTSSMULCx encountered a 
floating-point reserved operand due to incorrect 
user input. A floating-point reserved operand is 
a floating-point datum with a sign bit of 1 and a 
biased exponent of zero. Floating-point reserved 
operands are reserved for future use by DIGITAL. 


EXAMPLE 

C+ 

C This FORTRAN example forms the product of 
C two complex numbers using 0TS$MULCD_R3 
C and the FORTRAN random number generator RAN. 

C 

C Declare Zl, Z2, and Z_Q as complex values. 0TS$MULCD_R3 

C will return the complex product of Zl times by Z2: 

C Z_Q = Zl * Z2 
C- 

COMPLEX+16 Z1.Z2.Z_Q 
C+ 

C Generate a complex number. 

C- 

Z1 = (8.0,4.0) 

C+ 

C Generate another complex number. 

C- 

Z2 * (2.0,3.0) 

C+ 

C Compute the complex product of Z1*Z2. 

C- 

Z_Q = Zl * Z2 

TYPE *, ' The complex product of'.Zl,' times '.Z2,' is:' 

TYPE *, ' ',Z_Q 

END 


This FORTRAN example uses OTS$MULCD_R3 to multiply two complex 
numbers. The output generated by this program is as follows: 

The complex product of (8.000000000000000,4.000000000000000) times 
(2.000000000000000,3.000000000000000) is: 

( 4 . 000000000000000 . 32 . 00000000000000 ) 
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OTS$POWCxCx—Raise a Complex 

Base to a Complex 
Floating-Point Exponent 


OTS$POWCC, 0TS$P0WCDCD_R3 and 0TS$P0WCGCG_R3 
return the result of raising a complex base to a complex exponent. 

FORMAT 

OTS$POWCC base exponent 
OTS$POWCDCD_R3 base,exponent 
OTS$POWCGCG_R3 base,exponent 


Each of the above three formats corresponds to one of the three floating-point 
complex types. 

RETURNS 

VMS Usage: complex-number 

type: F_floating complex, D—floating complex, G_floating 

complex 

access: write only 

mechanism: by value 


Result of raising a complex base to a complex exponent. OTS$POWCC 
returns an F_floating complex number. OTS$POWCDCD—R3 returns a 

D—floating complex number. OTS$POWCGCG—R3 returns a G—floating 
complex number. 

ARGUMENTS 

base 

VMS Usage: complex—number 

type: F—floating complex, D_floating complex, G_floating 

complex 
access: read only 

mechanism: by value 

Complex base. The base argument contains the value of the base. 

For OTS$POWCC, base is an F—floating complex number. For 
OTS$POWCDCD—R3, base is a D—floating complex number. For 
OTS$POWCGCG—R3, base is a G—floating complex number. 


exponent 

VMS Usage: complex—number 

type: F_floating complex, D_floating complex, G—floating 

complex 
access: read only 

mechanism: by value 

Complex exponent. The exponent argument contains the value of the 
exponent. For OTS$POWCC, exponent is an F—floating complex number. 

For OTS$POWCDCD—R3, exponent is a D_floating complex number. For 
OTS$POWCGCG—R3, exponent is a G—floating complex number. 
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DESCRIPTION OTS$POWCC, OTS$POWCDCD_R3 and OTS$POWCGCG_R3 return 

the result of raising a complex base to a complex exponent. The American 
National Standard FORTRAN-77 (ANSI X3.9-1978) Standard defines complex 
exponentiation as: 

x y = cexpcy * clog(x)) 

where X and Y are type COMPLEX. 


CONDITION 

VALUES 

RETURNED 


MTH$_INVARGMAT 

MTH$_FLOOVEMAT 

SS$_ROPRAND 


Invalid argument in Math Library. Base is (0.,0.). 
Floating-point overflow in Math Library. 
Reserved operand. 


EXAMPLES 

B c- 

C This FORTRAN example forms the result of raising a complex base 
C to a complex power using OTSlPOWCC. 

C 

C Declare Z1, Z2, Z3, and OTSlPOWCC as complex values. Then OTSlPOWCC 

C will return the complex result of zl**z2: Z3 = OTSlPOWCC(Z1,Z2), 

C where Zl, and Z2 are passed by value. 

C- 

COMPLEX Z1.Z2.Z3,OTSlPOWCC 
C+ 

C Generate a complex base. 

C- 

Z1 = (2.0,3.0) 

C+ 

C Generate a complex power. 

C- 

Z2 * (1.0,2.0) 

C+ 

C Compute the complex value of Z1**Z2. 

C- 

Z3 = OTSlPOWCC( %VAL(REAL(Z1)), %VAL(AIMAG(Z1)), 

+ %VAL(REAL(Z2)) , y.VAL(AIMAG(Z2) ) ) 

TYPE *, ' The value of',Z1.'**',Z2,' is',Z3 
END 


This FORTRAN example uses OTS$POWCC to rasaise an F—floating complex 
base to an F_floating complex exponent. 

The output generated by this program is as follows: 

The value of (2.000000,3.000000)** (1.000000,2.000000) is 
(-0.4639565,-0.1995301) 
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C+ 

C 

C 

C 

C 

C 

C- 

C+ 


+ 




This FORTRAN example forms the result of raising a complex base 
to a complex power using 0TS$P0WCGCG_R3. 

Declare Zl, Z2, and Z3 as complex values. 0TS$P0WCGCG_R3 
will return the complex result of zl**z2: Z3 = Z1**Z2. 

COMPLEX*16 Z1,Z2,Z3 
Generate a complex base. 

Zl = (2.0,3.0) 

Generate a complex power. 

Z2 = (1.0,2.0) 

Compute the complex value of Z1**Z2. 

Z3 = Z1**Z2 
TYPE 1.Z1.Z2.Z3 

FORMAT(' The value of ( • ,F11.8,'.',F11.8,•)**(',F11.8, 

+ '.'.Fll.e,') is (' .F11.8, ' , ' , FI 1.8, '). ') 

END 


This FORTRAN example program shows how to use OTS$POWCGCG_R3. 
Notice the high precision in the output generated by this program: 


The value of ( 2.00000000, 3.00000000)**( 
(-0.46395650,-0.46395650). 


1.00000000, 2.00000000) is 
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OTS$POWCxJ—Raise a Complex Base to 



a Signed Longword 

Integer Exponent 

These procedures return the complex result of raising a complex 
base to an integer exponent. 

FORMAT 

OTS$POWCJ base,exponent 

OTS$POWCDJ_R3 base,exponent 
OTS$POWCGJ_R3 base exponent 

Each of the above three formats corresponds to one of the three floating-point 
complex types. 

RETURNS 

VMS Usage: complex_number 
type: F_floating complex 

access: write only 

mechanism: by value 

Complex result of raising a complex base to an integer exponent. 
OTS$POWCJ returns an F_floating complex number. OTS$POWCDJ— 

R3 returns a D_floating complex number. OTS$POWCGJ—R3 returns a 
G_floating complex number. In each format, the result and base are of the 
same data type. 

ARGUMENTS 

base 

VMS Usage: complex—number 

type: F—floating complex, D_floating complex, G— floating 

complex 
access: read only 

mechanism: by value 

Complex base. The base argument contains the complex base. For 
OTS$POWCJ, base is an F—floating complex number. For OTS$POWCDJ_ 
R3, base is a D—floating complex number. For OTS$POWCGJ_R3, base is a 
G_floating complex number. 

exponent 

VMS Usage: longword—signed 

type: longword integer (signed) 

access: read only 

mechanism: by value 

Exponent. The exponent argument is a signed longword integer containing 
the exponent. 
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DESCRIPTION OTS$POWCJ, OTS$POWCDJ_R3, and OTS$POWCGJ_R3 return the 

complex result of raising a complex base to an integer exponent. The complex 
result is as follows: 


Base 

Exponent 

Result 

Any 

Greater than 0 

The product of (6886*2*), 
where / is each nonzero 
bit in exponent 

(0,0.) 

Less than or equal to 0 

Undefined exponentiation 

Not (0.,0.) 

Less than 0 

The product of (base*2*), 
where / is each nonzero 
bit in exponent 

Not (0 ,0.) 

0 

(1.0,0.0) 


CONDITION SS$_FLTDIV 

VALUES SS$_FLTOVF 

SIGNALED MTH$_UNDEXP 


EXAMPLE 

c+ 

C This FORTRAN example forms the complex result of 
C raising a complex base to a NON-NEGATIVE integer 
C power using OTS$POWCJ. 

C 

C Declare Z1, Z2. Z3. and OTS$POWCJ as complex values. 

C Then 0TS$P0WCJ will return the complex result of 
C Z1**Z2: Z3 = OTS$POWCJ(Z1.Z2), 

C where Z1, and Z2 are passed by value. 

C- 

COMPLEX Z1.Z3,0TS$P0WCJ 
INTEGER Z2 
C+ 

C Generate a complex base. 

C- 

Z1 = (2.0,3.0) 

C+ 

C Generate an integer power. 

C- 

Z2 = 2 
C+ 

C Compute the complex value of Z1**Z2. 

C- 

Z3 = 0TS$P0WCJ( */,VAL(REAL (Zl) ) , %VAL(AIMAG(Z1)) , %VAL(Z2)) 

TYPE 1.Z1.Z2.Z3 

1 FORMAT(' The value of (',F10.8.',•,F11.8,')**',II,' is ('.F11.8, 

♦ '.'.F12.8,').') 

END 


Floating-point zero divide occurred. 
Floating-point overflow occurred. 
Undefined exponentiation. 


The output generated by this FORTRAN program is as follows: 

The value of (2.00000000, 3.00000000)**2 is (-6.00000000, 12.00000000). 
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OTS$POWDx—Exponentiation of 



D_floating Base 

OTS$POWDD, OTS$POWDJ, and OTS$POWDR raise a D_floating 
base to a D_floating, longword, or F_floating exponent. 

FORMAT 

OTS$POWDD base,exponent 

OTS$POWDJ base,exponent 

OTS$POWDR base exponent 

The above formats correspond to raising the D__floating base to a D—floating, 
longword, or F—floating exponent. 

RETURNS 

VMS Usage: floating-point 
type: D_floating 

access: write only 

mechanism: by value 

D—floating result. Regardless of the type of the exponent, the result is always 
a D—floating number. 

ARGUMENTS 

base 

VMS Usage: floating-point 
type: D_floating 

access: read only 

mechanism: by value 

Base. The base argument is a D—floating number containing the base. 

exponent 

VMS Usage: floating-point 

type: D—floating, longword integer (signed), F—floating 

access: read only 

mechanism: by value 

Exponent. The exponent argument contains the exponent. For 
OTS$POWDD, exponent is a D—floating number. For OTS$POWDJ, 
exponent is a signed longword integer. For OTS$POWDR, exponent is an 
F_iloating number. 


DESCRIPTION OTS$POWDD, OTS$POWDJ and OTS$POWDR raise a D_floating base to a 
D—floating, longword, or F_floating exponent. 

OTS$POWDD, OTS$POWDJ, and OTS$POWDR use the same basic 
algorithm. However, the internal calculations and the floating-point result are 
computed at the same precision level as that of the base value. 
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OTS$POWDD 

The D_floating result for OTS$POWDD is given by: 


Base 

Exponent 

Result 

=0 

> 0 

0.0 

=0 

=0 

Undefined exponentiation 

=0 

<0 

Undefined exponentiation 

<0 

Any 

Undefined exponentiation 

> 0 

> 0 

2 [exponent*DLOG2(base)] 

> 0 

=0 

1.0 

> 0 

<0 

2[exponent*DLOG2(base)] 


Floating-point overflow can occur. 

Undefined exponentiation occurs if the base is 0 and the exponent is 0 or 
negative, or if the base is negative. 

OTSSPOWDJ 

The floating-point result is as follows: 


Base 

Exponent 

Result 

Any 

> 0 

Product of (base*2 l ) where / is each nonzero bit position in 

1 exponent 1 

> 0 

=0 

1.0 

=0 

=0 

Undefined exponentiation 

<0 

=0 

1.0 

> 0 

<0 

1.0/product of (base*2 l ), where / is each nonzero bit 
position in lexponentl 

=0 

<0 

Undefined exponentiation 

<0 

<0 

1.0/product of (base*2 l ) where / is each nonzero bit 
position in lexponentl 


Floating-point overflow can occur. 

Undefined exponentiation occurs if the base is 0 and the exponent is 0 or 
negative. 

OTS$POWDR 

OTS$POWDR converts the F__floating exponent to a D_Jloating number. 
OTS$POWDR then calculates the D_iloating result in the same way that it 
calculates the result for OTS$POWDD. 
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CONDITION 

VALUES 

RETURNED 


SSS—FLTOVF 

MTH$_FLOOVEMAT 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 

Floating-point overflow in Math Library. 
Floating-point underflow in Math Library. 

Undefined exponentiation. This error is signaled if 
base is zero and exponent is zero or negative, or if 
the base is negative. 
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OTS$POWGx—Raise G_floating Base to 



G_floating or Longword 
Exponent 

OTS$POWGG and OTS$POWGJ raise a G_floating base to a 
G_floating or longword exponent. 

FORMAT 

OTS$POWGG base,exponent 

OTS$POWGJ base exponent 

RETURNS 

VMS Usage: floating-point 
type: G_floating 

access: write only 

mechanism: by value 

Result of the exponentiation. Regardless of whether the base is raised to a 

G—floating or longword exponent, the result is always a G_floating number. 

ARGUMENTS 

base 

VMS Usage: floating-point 
type: G_floating 

access: read only 

mechanism: by value 

Base which OTS$POWGx raises to a G—floating or longword exponent. The 
base argument is a G—floating number containing the base. 

exponent 

VMS Usage: floating-point 

type: G_floating, longword integer (signed) 

access: read only 

mechanism: by value 

Exponent to which OTS$POWGx raises the base. For OTS$POWGG, 
the exponent argument is a G_floating number containing the exponent. 

For OTS$POWGJ, the exponent argument is a signed longword integer 
containing the exponent. 


DESCRIPTION OTS$POWGG, and OTS$POWGJ raise a G-floating base to a G-floating or 
longword exponent. 

OTS$POWGG and OTS$POWGJ use the same basic algorithm. However, the 
internal calculations and the floating-point result are computed at the same 
precision level as that of the base value. 
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CONDITION 

VALUES 

RETURNED 


OTS$POWGG 

The G__floating result for OTS$POWGG is as follows: 


Base 

Exponent 

Result 

=0 

> 0 

0.0 

=0 

=0 

Undefined exponentiation 

=0 

<0 

Undefined exponentiation 

<0 

Any 

Undefined exponentiation 

> 0 

> 0 

2[exponent*GLOG2(base)] 

> 0 

=0 

1.0 

> 0 

<0 

2[exponent*GLOG2(base)] 


Floating-point overflow can occur. 

Undefined exponentiation occurs if the base is 0 and the exponent is 0 or 
negative, or if the base is negative. 

OTSSPOWGJ 

The floating-point result is as follows: 


Base 

Exponent 

Result 

Any 

> 0 

Product of (base*2 i ) where / is each nonzero bit position in 

1 exponent! 

> 0 

=0 

1.0 

=0 

=0 

Undefined exponentiation 

<0 

=0 

1.0 

> 0 

<0 

1.0/product of (base*2 i ) / where / is each nonzero bit 
position in 1 exponent! 

=0 

<0 

Undefined exponentiation 

<0 

<0 

1.0/Product of (base*2*) where / is each nonzero bit 
position in lexponentl 


Floating-point overflow can occur. 

Undefined exponentiation occurs if the base is 0 and the exponent is 0 or 
negative. 


SS$_FLTOVF 

MTHS—FLOOVEMAT 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 

Floating-point overflow in Math Library. 
Floating-point underflow in Math Library. 

Undefined exponent. This error is signaled if base 
is zero and exponent is zero or negative, or if base 
is negative. 
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EXAMPLE 

O 

C This example demonstrates the use of 0TS$P0WGG, 

C which raises a G.floating point base 
C to a G_floating point power. 

C- 

REAL*8 X,Y,RESULT,0TS$P0WGG 
C+ 

C The arguments of 0TS$P0WGG are passed by value. FORTRAN can 
C only pass INTEGER and REAL*4 expressions as VALUE. Since 
C INTEGER and REAL*4 values are one longword long, while REAL*8 
C values are two longwords long, equate the base (and power) to 
C a two dimensional INTEGER vector. These vectors will be passed 
C by VALUE. 

C- 

INTEGER N(2),M(2) 

EQUIVALENCE (N(1),X), (M(l),Y) 

X = 8.0 

Y = 2.0 
C+ 

C To pass X by value, pass N(l) and N(2) by value. Similarly for Y. 

C- 

RESULT = 0TS$P0WGG(7.VAL(N(l)),y.VAL(N(2)),7.VAL(M(l)).y.VAL(M(2))) 
TYPE *.' 8.0**2.0 IS '.RESULT 
X = 9.0 

Y = -0.5 
C+ 

C In FORTRAN, 0TS$P0WWGG is indirectly called by simply using the 
C exponentiation operator. 

C- 

RESULT = X**Y 

TYPE *.' 9.0**-0.5 IS ',RESULT 
END 


This FORTRAN example uses OTS$POWGG to raise a G__floating base to a 
G_floating power. 

The output generated by this example is as follows: 

8.0**2.0 IS 64.0000000000000 
8.0**2.0 IS 0.333333333333333 
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OTS$POWHx—Exponentiation, H_floating 



Base 

0TS$P0WHH_R3 and 0TS$P0WHJ_R3 raise an H_floating base 
to an H_floating or longword exponent. 

FORMAT 

OTS$POWHH_R3 base exponent 
OTS$POWHJ_R3 base .exponent 

The above formats correspond to raising an H_floating number to either an 
H—floating or a signed longword integer exponent. 

RETURNS 

VMS Usage: floating-point 
type: H_floating 

access: write only 

mechanism: by value 

H_floating result. Regardless of the type of the exponent, the result is always 
an H_floating number. 

ARGUMENTS 

base 

VMS Usage: floating-point 
type: H_floating 

access: read only 

mechanism: by value 

Base. The base argument is an H— floating number containing the base. 

exponent 

VMS Usage: longword—signed 

type: H_floating, longword integer (signed) 

access: read only 

mechanism: by value 

Exponent. The exponent argument contains the exponent. For 
OTS$POWHH_R3, exponent is an H_floating number. For 

OTS$POWHJ_R3, exponent is a signed longword integer. 

DESCRIPTION 

OTS$POWHH and OTS$POWHJ raise an H—floating base to an H_floating 
or longword exponent. 

OTS$POWHH and OTS$POWHJ use the same basic algorithm. However, the 
internal calculations and the floating-point result are computed at the same 
precision level as that of the base value. 
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OTS$POWHH 

The H_iloating result for OTS$POWHH is as follows: 


Base 

Exponent 

Result 

=0 

> 0 

0.0 

=0 

=0 

Undefined exponentiation 

=0 

<0 

Undefined exponentiation 

<0 

Any 

Undefined exponentiation 

> 0 

> 0 

2[exponent*HLOG2(base)] 

> 0 

=0 

1.0 

> 0 

<0 

2[exponent*HLOG2(base)] 


Floating-point overflow can occur. 

Undefined exponentiation occurs if the base is 0 and the exponent is 0 or 
negative, or if the base is negative. 

OTS$POWHJ 

The floating-point result is as follows: 


Base 

Exponent 

Result 

Any 

> 0 

Product of (base*2 l ) where / is each nonzero bit position in 

1exponent 1 

> 0 

=0 

1.0 

=0 

=0 

Undefined exponentiation 

<0 

=0 

1.0 

> 0 

<0 

1.0/product of (base*2 l ), where / is each nonzero bit 
position in 1 exponent 1 

=0 

<0 

Undefined exponentiation 

<0 

<0 

1.0/product of (base*2*) where / is each nonzero bit 
position in lexponentl 


Floating-point overflow can occur. 

Undefined exponentiation occurs if the base is 0 and the exponent is 0 or 
negative. 


SS$_FLTOVF 

MTH$_FLOOVEMAT 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 

Floating-point overflow in Math Library. 
Floating-point underflow in Math Library. 

Undefined exponentiation. This error is signaled if 
base is zero and exponent is zero or negative, or if 
the base is negative. 
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EXAMPLE 


Example of 0TS$P0WHH, which raises a H.floating 
point base to an H_floating point power. In FORTRAN, 
it is not directly called. 

REAL*16 X,Y,RESULT 
X = 9877356535.0 
Y = -0.5837653 

C In FORTRAN, OTSlPOWWHH is indirectly called by simply using the 
C exponentiation operator. 

C- 

RESULT = X**Y 

TYPE *,' 9877356535.0**-0.5837653 IS '.RESULT 
END 


This FORTRAN example demonstrates how to call OTS$POWHH to raise an 
H_floating base to an H_floating power. 

The output generated by this program is as follows: 

8.0**2.0 IS 1.463779145994628357482343598205427E-0006 
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OTS$POWII—Exponentiation, Word Base 



OTS$POWII raises a word base to a word exponent. 

FORMAT 

OTS$POWII base,exponent 

RETURNS 

VMS Usage: word_signed 
type: word integer (signed) 

access: write only 

mechanism: by value 

Result of raising a word base to a word exponent. 

ARGUMENTS 

base 

VMS Usage: word-signed 
type: word integer (signed) 

access: read only 

mechanism: by value 

Base. The base argument is a signed word integer containing the base. 

exponent 

VMS Usage: word_signed 
type: word integer (signed) 

access: read only 

mechanism: by value 

Exponent. The exponent argument is a signed word integer containing the 
exponent. 

CONDITION 

VALUES 

RETURNED 

SSS—FLTDIV Arithmetic trap. This error is signaled by the 

hardware if a floating-point zero divide occurs. 

SS$_FLTOVF Arithmetic trap. This error is signaled by the 

hardware if a floating-point overflow occurs. 

MTH$_UNDEXP Undefined exponentiation. This error is signaled if 

base is zero and exponent is zero or negative, or if 


base is negative. 


RTL-522 












Run-Time Library Routines 

OTS$POWJJ 


OTS$POWJJ—Raise a Longword Base to 



a Longword Exponent 

OTS$POWJJ raises a signed longword base to a signed longword 
exponent. 

FORMAT 

OTS$POWJJ base exponent 

RETURNS 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by value 

Result of raising a longword base to a longword exponent. 

ARGUMENTS 

base 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Base. The base argument is a signed longword integer containing the base. 

exponent 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Exponent. The exponent argument is a signed longword integer containing 
the exponent. 

CONDITION 

VALUES 

SIGNALED 

SS$_FLTDIV Arithmetic trap. This error is signaled by the 

hardware if a floating-point zero divide occurs. 

SS$_FLTOVF Arithmetic trap. This error is signaled by the 

hardware if a floating-point overflow occurs. 

MTH$_UNDEXP Undefined exponentiation. This error is signaled if 

base is zero and exponent is zero or negative, or 


if base is negative. 
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OTS$POWLULU 

Raise an Unsigned Longword Integer Base 
to an Unsigned Longword Exponent 



OTS$POWLULU returns the result of raising an unsigned longword 
integer base to an unsigned longword integer exponent. 

FORMAT 

OTS$POWLULU base, exponent 

RETURNS 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Result of raising an unsigned longword integer base to an unsigned longword 
integer exponent. This function value is returned in RO. 

ARGUMENTS 

base 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by value 

Unsigned longword integer base. The base argument contains the value of 
the integer base. 

exponent 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by value 

Unsigned longword integer exponent. The exponent argument contains the 
value of the integer exponent. 


DESCRIPTION OTS$POWLULU returns the unsigned longword integer result of raising an 



unsigned longword integer base to an unsigned longword integer exponent. 
Note that overflow cannot occur in this routine. If the result or intermediate 
result is greater than 32 bits, the low-order 32 bits are used. 

CONDITION 

VALUES 

RETURNED 

MTH$_UNDEXP Both the base and exponent values are zero. 
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OTS$POWxLU 

Raise a Floating-Point Base to an Unsigned 
Longword Integer Exponent 



OTS$POWRLU, OTS$POWDLU, OTS$POWGLU, and 
0TS$P0WHLU_R3 return the result of raising a floating-point base 
to an unsigned longword integer exponent. 

FORMAT 

OTS$POWRLU base,exponent 

OTS$POWDLU base exponent 

OTS$POWGLU base,exponent 

OTS$POWHLU_R3 base,exponent 

RETURNS 

VMS Usage: floating-point 

type: F_floating, D_floating, G-floating, H—floating 

access: write only 

mechanism: by value 

Result of raising a floating-point base to an unsigned longword integer 
exponent. OTS$POWRLU returns an E-floating number. OTS$POWDLU 
returns a D_floating number. OTS$POWGLU returns a G—floating number. 
OTS$POWHLU—R3 returns an H_floating number. 

ARGUMENTS 

base 

VMS Usage: floating-point 

type: F—floating, D_floating, G_floating, H_floating 

access: read only 

mechanism: by value 

Floating-point base. The base argument contains the value of the base. For 
OTS$POWRLU, base is an F—floating number. For OTS$POWDLU, base is a 
D_floating number. For OTS$POWGLU, base is a G_floating number. For 
OTS$POWHLU_R3, base is an H_floating number. 

exponent 

VMS Usage: longword—unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by value 

Integer exponent. The exponent argument contains the value of the unsigned 
longword integer exponent. 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


OTS$POWRLU, OTS$POWDLU, OTS$POWGLU, and OTS$POWHLU_R3 
return the result of raising a floating-point base to an unsigned longword 
integer exponent. The floating-point result is as follows: 


Base 

Exponent 

Result 

Any 

Greater than 0 

The product of (base*2') / 
where /' is each nonzero bit 



in exponent 

Greater than 0 

0 

1.0 

0 

0 

Undefined exponentiation 

Less than 0 

0 

1.0 


MTH$_FLOOVEMAT 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 


Floating-point overflow in Math Library 

Floating-point underflow in Math Library. This can 
only occur if the caller has floating-point underflow 
enabled. 

Undefined exponentiation. This occurs if both the 
base and exponent arguments are zero. 
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OTS$POWRx—Exponentiation, F—floating 



Base 

OTS$POWRD, OTS$POWRJ, and OTS$POWRR raise an F_floating 
base to a D_floating, longword,or F_floating exponent. 

FORMAT 

OTS$POWRD base,exponent 

OTS$POWRJ base,exponent 

OTSSPOWRR base,exponent 

The above formats correspond to raising the base to a D_floating, longword 
and F_floating exponent. 

RETURNS 

VMS Usage: floating-point 
type: F—floating 

access: write only 

mechanism: by value 

Result. OTS$POWRJ returns an F-floating number. OTS$POWRR returns an 
F_floating number. (If the exponent is F_floating or a longword integer, the 
result is F—floating.) OTS$POWRD returns a D_floating number. 

ARGUMENTS 

base 

VMS Usage: floating-point 
type: F—floating 

access: read only 

mechanism: by value 

Base. The base argument is an F—floating number containing the base. 

exponent 

VMS Usage: varying.arg 

type: D—floating, longword integer (signed), F—floating 

access: read only 

mechanism: by value 

Exponent. The exponent argument contains the exponent. For 
OTS$POWRD, exponent is a D-floating number. For OTS$POWRJ, exponent 
is a signed longword integer. For OTS$POWRR, exponent is an F—floating 
number. 

DESCRIPTION 

OTS$POWRD, OTS$POWRJ and OTS$POWRR raise a F_floating base to a 
D-floating, longword, or F—floating exponent. 

OTS$POWRD, OTS$POWRJ and OTS$POWRR use the same basic algorithm. 
However, the internal calculations and the floating-point result are computed 
at the same precision level as that of the base value. 
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OTS$POWRR 

The F_floating result for OTS$POWRR is as follows: 


Base 

Exponent 

Result 

=0 

> 0 

0.0 

=0 

=0 

Undefined exponentiation 

=0 

<0 

Undefined exponentiation 

<0 

Any 

Undefined exponentiation 

> 0 

> 0 

2[exponent*LOG2(base)] 

> 0 

=0 

1.0 

> 0 

<0 

2[exponent*LOG2(base)] 


Floating-point overflow can occur. 

Undefined exponentiation occurs if the base is zero and the exponent is zero 
or negative, or if the base is negative. 

OTSSPOWRJ 

The floating-point result is as follows: 


Base 

Exponent 

Result 

Any 

> 0 

Product of (base*2*) where /'is each nonzero bit position in 

1exponent 1 

> 0 

=0 

1.0 

=0 

=0 

Undefined exponentiation 

<0 

=0 

1.0 

> 0 

<0 

1.0/product of (base*2 l ), where / is each nonzero bit 
position in 1 exponent 1 

=0 

<0 

Undefined exponentiation 

<0 

<0 

1.0/product of (base*2 l ) where / is each nonzero bit 
position in 1 exponent 1 


Floating-point overflow can occur. 

Undefined exponentiation occurs if the base is 0 and the exponent is 0 or 
negative. 

OTSSPOWRD 

OTS$POWRD first converts the F_floating base to D_floating. OTS$POWRD 
then calculates the F_floating result in the same way that it calculates the 
result for OTS$POWRR. 
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CONDITION SS$_FLTOVF 

VALUES 

RETURNED mth$_floo vem at 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 

Floating-point overflow in Math Library. 
Floating-point underflow in Math Library. 

Undefined exponentiation. This error is signaled if 
base is zero and exponent is zero or negative, or if 
base is negative. 


EXAMPLES 


C This FORTRAN example demonstrates the use 
C of OTSIPOWRR, which raises an F_floating 
C point base to an F_floating point power. 

C- 

REAL+4 X,Y,RESULT,OTS$POWRR 

X = 8.0 

Y = 2.0 
C+ 

C The arguments of 0TS$P0WRR are passed by value. 

C- 

RESULT = 0TS$P0WRR(y.VAL(X),7.VAL(Y)) 

TYPE *.' 8.0**2.0 IS '.RESULT 
X = 9.0 

Y = -0.5 

C+ 

C In FORTRAN, 0TS$P0WRR is indirectly called by simply 
C using the exponentiation operator. 

C- 

RESULT = X**Y 

TYPE *,' 9.0**-0.5 IS '.RESULT 
END 


This FORTRAN example uses OTS$POWRR to raise an F_floating point base 
to an F_floating point power. The output generated by this program is as 
follows: 

8.0**2.0 IS 64.00000 

9.0**-0.5 IS 0.3333333 


C This FORTRAN example demonstrates the use 
C of 0TS$P0WRD, which raises an F_floating point 
C base to a D_floating point power. The result is a 
C D.floating value. 

C- 

REAL*4 X 

REAL*8 Y.RESULT,0TS$P0WRD 
INTEGER M(2) 

EQUIVALENCE (M(1),Y) 

X = 9768.0 
Y = 9.0 

C+ 

C The arguments of OTSlPOWRD are passed by value. 

C- 


RESULT = 0TS$P0WRD(y.VAL(X),y.VAL(M(l)).%VAL(M(2))) 
TYPE *,' 9768.0**9.0 IS ' .RESULT 
X = 7689.0 
Y = -0.587436654545 
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In FORTRAN, 0TS$P0WRD is indirectly called by simply 
using the exponentiation operator. 


RESULT = X**Y 

TYPE *,' 7689.0**-0.587436654545 IS '.RESULT 
END 


This FORTRAN example uses OTS$POWRD to raise an F_floating base 
to a D_floating exponent. Notice the difference in the precision of the 
result produced by this routine in comparison to the result produced by 
OTS$POWRR. 

The output generated by this program is as follows: 

9768.0**9.0 IS 8.0956338648832908E+35 

7689.0**-0.587436654545 IS 5.2155199252836588E-03 
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OTS$SCOPY_DXDX—Copy a Source 
String Passed by Descriptor to a 
Destination String 

OTS$SCOPY_DXDX copies a source string to a destination string. 
Both strings are passed by descriptor. 


FORMAT OTS$SCOPY_DXDX src-str ,dst-str 


corresponding OTS$SCOPY_DXDX6 
jsb entry point 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


word-unsigned 
word (unsigned) 
write only 
by value 


If src-str contains more characters than dst-str, and the JSB entry point is 
used, RO contains the number of characters that were not copied. 


ARGUMENTS 


src-str 

VMS Usage 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 

Source string. The src-str argument is the address of a descriptor pointing 
to the source string. The descriptor class can be unspecified, fixed length, 
dynamic, scalar decimal, array, noncontiguous array, or varying. 


dst-str 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
write only 
by descriptor 

Destination string. The dst-str argument is the address of a descriptor 
pointing to the destination string. The class field determines the appropriate 
action. 

See the Description section for further information. 


DESCRIPTION OTS$SCOPY_DXDX copies a source string to a destination string. All error 
conditions except truncation are signaled; truncation is ignored. 

OTS$SCOPY_DXDX passes the source string by descriptor. In addition, an 
equivalent JSB entry point is provided, with RO being the first argument (the 
descriptor of the source string), and R1 the second (the descriptor of the 
destination string). 
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CONDITION 

VALUES 

SIGNALED 


For the CALL entry point, RO (return status) is as it would be after a MOVC5 
instruction. For the JSB entry point, R0:R5 and the PSL are as they would be 
after a MOVC5 instruction. R0:R5 contain the following: 

RO = Number of bytes of source string not moved to destination string 

R1 = Address one byte beyond the last byte in the source string that was 
moved 

R2 = 0 

R3 = Address one byte beyond the destination string 

R4 = 0 

R5 = 0 

For further information, see the VAX-11 Architecture Reference Manual. 

Depending on the class of the destination string, the actions described below 
occur: 


Class Field 

Action 

DSC$K_CLASS_S,Z,SD,A,NCA 

Copy the source string. If needed, space fill 
or truncate on the right. 

DSC$K_CLASS_D 

If the area specified by the destination 
descriptor is large enough to contain the 
source string, copy the source string and set 
the new length in the destination descriptor. 

If the area specified is not large enough, 
return the previous space allocation (if any) 
and then dynamically allocate the amount 
of space needed. Copy the source string 
and set the new length and address in the 
destination descriptor. 

DSC$K_CLASS_VS 

Copy source string to destination string up 
to the limit of DSC$W_MAXSTRLEN with 
no padding. Readjust current length field to 
actual number of bytes copied. 


OTS$_FATINTERR 

OTS$_INVSTRDES 

OTS$_INSVIRMEM 


Fatal internal error. 

Invalid string descriptor. 
Insufficient virtual memory. 
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OTS$SCOPY_R_DX_Copy a Source 
String Passed by Reference to a 
Destination String 

OTS$SCOPY_R_DX copies a source string passed by reference to 



a destination string. 

FORMAT 

OTS$SCOPY_R_DX src-len ,src-adr,dst-str 

corresponding 
jsb entry point 

OTS$SCOPY_R_DX6 

RETURNS 

VMS Usage: word—unsigned 
type: word (unsigned) 

access: write only 

mechanism: by value 

If src-str contains more characters than dst-str, and the JSB entry point is 
used, RO contains the number of characters that were not copied. 

ARGUMENTS 

src-len 

VMS Usage: word—unsigned 
type: word (unsigned) 

access: read only 

mechanism: by value 

Length of the source string. The src-len argument is an unsigned word 
integer containing the length of the source string. 

src-adr 

VMS Usage: char—string 
type: character string 

access: read only 

mechanism: by reference 

Source string. The src-adr argument is the address of the source string. 

dst-str 

VMS Usage. char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string. The dst-str argument is the address of a descriptor 
pointing to the destination string. The class field determines the appropriate 
action. The length field (DSC$W_LENGTH) alone or both the address 
(DSC$A—POINTER) and length fields can be modified if the string is 
dynamic. For varying strings, the current length is rewritten. 


RTL-530 









Run-Time Library Routines 

OTS$SCOPY_R_DX 


DESCRIPTION 


CONDITION 

VALUES 

SIGNALED 


OTS$SCOPY_R_DX copies a source string to a destination string. All 
conditions except truncation are signaled; truncation is ignored. Input scalars 
are passed by value. 

OTS$SCOPY_R_DX passes the source string by reference preceded by a 
length argument. In addition, an equivalent JSB entry point is provided, with 
RO being the first argument, R1 the second, and R2 the third, if any. The 
length argument is passed in bits 15:0 of the appropriate register. 

For the CALL entry point, RO (return status) is as it would be after a MOVC5 
instruction. For the JSB entry point, R0:R5 and the PSL are as they would be 
after a MOVC5 instruction. R0:R5 contain the following: 

RO = Number of bytes of source string not moved to destination string 

R1 = Address one byte beyond the last byte in the source string that was 
moved 

R2 = 0 

R3 = Address one byte beyond the destination string 

R4 = 0 

R5 = 0 

(For additional information, see the VAX-11 Architecture Reference Manual.) 

Depending on the class of the destination string, the actions described below 
occur: 


Class Field 

Action 

DSC$K_CLASS_S,Z,SD,A,NCA 

Copy the source string. If needed, space fill 
or truncate on the right. 

DSC$K_CLASS_D 

If the area specified by the destination 
descriptor is large enough to contain the 
source string, copy the source string and set 
the new length in the destination descriptor. 

If the area specified is not large enough, 
return the previous space allocation (if any) 
and then dynamically allocate the amount 
of space needed. Copy the source string 
and set the new length and address in the 
destination descriptor. 

DSC$K_CLASS_VS 

Copy source string to destination string up 
to the limit of DSC$W_MAXSTRLEN with 
no padding. Readjust current length field to 
actual number of bytes copied. 


OTS$_FATINTERR 

OTS$_INVSTRDES 

OTS$_INSVIRMEM 


Fatal internal error. 

Invalid string descriptor. 
Insufficient virtual memory. 
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EXAMPLE 


A FORTRAN example demonstrating dynamic string manipulation appears 
at the end of OTS$SGETl_DD. This example uses OTS$SCOPY_R_DX, 
OTS$SGETl_DD, and OTS$SFREEl_DD. 
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OTS$SFREE1_DD—Strings, Free One 



Dynamic 

OTS$SFREE1_DD returns one dynamic string area to free storage. 

FORMAT 

OTS$SFREE1 _DD dyn-dsc 

corresponding 
jsb entry point 

OTS$SFREE1_DD6 

RETURNS 

None. 

ARGUMENTS 

dyn-dsc 

VMS Usage: quadword__unsigned 
type: quadword (unsigned) 

access: modify 

mechanism: by reference 

Dynamic string descriptor. The dyn-dsc argument is the address of the 
dynamic string descriptor. The descriptor is assumed to be dynamic and its 
class field is not checked. 


DESCRIPTION OTS$SFREEl_DD deallocates the described string space and flags the 

descriptor as describing no string at all (DSC$A_POINTER = 0 and DSC$W_ 



LENGTH = 0). 

CONDITION 

VALUE 

SIGNALED 

OTSS—FATINTERR Fatal internal error. 


EXAMPLE 


A FORTRAN example demonstrating dynamic string manipulation appears 
at the end of OTS$SGETl_DD. This example uses OTS$SFREEl__DD, 
OTS$SGETl_DD, and OTS$SCOPY_R_DX. 
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OTS$SFREEN_DD—Strings, Free n 



Dynamic 

OTS$SFREEN_DD takes as input a vector of one or more dynamic 
string areas and returns them to free storage. 

FORMAT 

OTS$SFREEN_DD dsc-num,first-dsc 

corresponding 
jsb entry point 

OTS$SFREEN_DD6 

RETURNS 

None. 

ARGUMENTS 

dsc-num 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by value 

Number of adjacent descriptors to be flagged as having no allocated area 

(DSC$A_POINTER - 0 and DSC$W_LENGTH = 0) and to have their 

allocated areas returned to free storage by OTS$SFREEN_DD. The dsc-num 
argument is an unsigned longword containing this number. 

first-dsc 

VMS Usage: quadword_unsigned 
type: quadword (unsigned) 

access: modify 

mechanism: by reference 

First string descriptor of an array of string descriptors. The first-dsc argument 
is the address of the first string descriptor. The descriptors are assumed to be 
dynamic, and their class fields are not checked. 


DESCRIPTION OTS$SFREEN_DD6 deallocates the described string space and flags each 

descriptor as describing no string at all (DSC$A_POINTER - 0 and DSC$W_ 



LENGTH = 0). 

CONDITION 

VALUE 

SIGNALED 

OTS$_FATINTERR Fatal internal error. 
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OTS$SGET1_DD—Strings, Get One 



Dynamic 

0TS$SGET1_DD allocates a specified number of bytes of dynamic 
virtual memory to a specified string descriptor. 

FORMAT 

OTS$SGET1 _DD len ,dyn-dsc 

corresponding 
jsb entry point 

OTS$SGET1_DD_R6 

RETURNS 

None. 

ARGUMENTS 

len 

VMS Usage: word—unsigned 
type: word (unsigned) 

access: read only 

mechanism: by value 

Number of bytes to be allocated. The len argument contains the number of 
bytes. The amount of storage allocated is automatically rounded up. If the 
number of bytes is zero, a small number of bytes is allocated. 

dyn-dsc 

VMS Usage: quadword—unsigned 
type: quadword (unsigned) 

access: modify 

mechanism: by reference 

Dynamic string descriptor to which the area is to be allocated. The dyn-str 
argument is the address of the dynamic string descriptor. The class field is 
not checked but it is set to dynamic (DSC$B_CLASS = 2). The length field 
(DSC$W—LENGTH) is set to len and the address field (DSC$A_POINTER) is 
set to the string area allocated (first byte beyond the header). 

DESCRIPTION 

OTS$SGETl—DD allocates a specified number of bytes of dynamic virtual 
memory to a specified string descriptor. This procedure is identical to 
OTS$SCOPY_DXDX except that no source string is copied. You can write 
anything you want in the allocated area. 

If the specified string descriptor already has dynamic memory allocated to it, 
but the amount allocated is either greater than or less than len, that space is 
deallocated before OTS$SGETl_DD allocates new space. 
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CONDITION 

OTS$_FATINTERR 

Fatal internal error. 

VALUES 

OTS$_INSVIRMEM 

Insufficient virtual memory. 

SIGNALED 




EXAMPLE 


PROGRAM STRING.TEST 


C+ 

C This program demonstrates the use of some dynamic string 

C manipulation routines. 

C- 

C* 

C DECLARATIONS 

C- 

IMPLICIT NONE 
CHARACTER*80 DATA.LINE 

INTEGER*4 DATA.LEN, DSC(2), CRLF_DSC(2). TEMP_DSC(2) 

CHARACTER*2 CRLF 

C+ 

C Initialize the output descriptor. It should be empty. 

C- 

CALL 0TS$SGETl_DD(y.VAL(0) . DSC) 

C+ 

C Initialize a descriptor to the string CRLF and copy the 

C character CRLF to it. 

C- 

CALL 0TS$SGET1_DD(%VAL(2), CRLF.DSC) 

CRLF = CHAR(13)//CHAR(10) 

CALL 0TS$SC0PY_R.DX( %VAL(2), */,REF(CRLF(1:1)), CRLF.DSC) 

C+ 

C Initialize a temporary descriptor. 

C- 

CALL 0TS$SGET1_DD(XVAL(0), TEMP.DSC) 

C+ 

C Prompt the user. 

C- 

WRITE(6. 999) 

999 F0RMAT(1X, 'Enter your message, end with CTRL/Z.') 

C+ 

C Read lines of text from the terminal until end-of-file. 

C Concatenate each line to the previous input. Include a 

C CRLF between each line. 

C- 

DO WHILE (.TRUE.) 

READ(5. 998, ERR * 10) DATA.LEN, DATA.LINE 
998 FORMAT(Q,A) 

CALL 0TS$SC0PY_R_DX( %VAL(DATA.LEN), 

1 XRE1F (DATA.LINE (1:1) ) , 

2 TEMP.DSC) 

CALL STR$CONCAT( DSC. DSC. TEMP.DSC, CRLF.DSC ) 

END DO 

C+ 

C The user has typed CTRL/Z. Output the data we read. 

C- 

10 CALL LIB$PUT_OUTPUT( DSC ) 
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C+ 

C Free the storage allocated to the dynamic strings. 

C- 

CALL 0TS$SFREE1_DD( DSC ) 

CALL 0TS$SFREE1_DD( CRLF.DSC ) 

CALL 0TS$SFREE1_DD( TEMP.DSC ) 

C+ 

End of program. 


STOP 

END 


This FORTRAN example program demonstrates dynamic string manipulation 
using OTS$SGETl_DD, OTS$SFREE 1_DD, and OTS$SCOPY_R_DX. 


April 1986 


RTL-537 



Run-Time Library Routines 

SMG$ADD_KEY_DEF 


SMG$ADD_KEY_DEF- 

—Add Key Definition 


SMG$ADD_KEY_DEF adds a keypad key definition to a table of key 
definitions. 

FORMAT 

SMG$ADD_KEY_ 

DEF key-table-id,key-name 
[,if-state] [,attributes] 

[, equiv-string] [, state-string] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

key-table-id 



VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Identifies the key table to which you are adding a key definition. The key- 
table-id argument is the address of an unsigned longword that contains the 
key table identifier. 

Key-table-id is returned by the SMG$CREATE _JCEY_TABLE routine. 

key-name 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Identifies the key whose value you are defining. The key-name argument is 
the address of a descriptor pointing to this key name. The SMG$ADD__KEY_ 
DEF procedure changes the string to uppercase and removes trailing blanks. 

Table 3-1 in Part I of this manual lists the valid key names. 


if-state 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Qualifies the value returned when key-name is struck. The if-state argument 
is the address of a descriptor pointing to the state string. 


If if-state is specified, this definition of key-name is used only if the current 
state matches the specified if-state string. The if-state argument must be 
from 1 to 31 characters in length. If this argument is omitted, if-state defaults 
to the value "DEFAULT." 
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attributes 


VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Longword bit mask specifying additional attributes of this key definition. The 
attributes argument is the address of an unsigned longword that contains this 
attribute mask. If omitted, the mask is zero. 


Valid attributes are described in the following list: 


SMG$M_KEY_NOECHO 


SMG$M_KEY_TERMINATE 


SMG$M_KEY_LOCKST ATE 


SMG$M_KEY_PROTECTED 


If set, this bit specifies that equiv_ 
string is not to be echoed when 
this key is pressed. If clear, equiv_ 
string is echoed. If SMG$M_KEY_ 
TERMINATE is not set, SMG$M_ 
KEY—NOECHO is ignored. 

If set, this bit specifies that when 
this key is pressed (as qualified by if- 
state) that the input line is complete, 
and more characters should not be 
accepted. If clear, more characters 
may be accepted. In other words, 
setting this bit causes equivalence 
string to be treated as a terminator. 

If set, and if state-string is 
specified, the state name specified 
by state-string remains the current 
state until explicitly changed by 
a subsequent keystroke whose 
definition includes a state-string. If 
clear, the state name specified by 
state-string remains in effect only 
for the next defined keystroke. 

If set, this bit specifies that this 
key definition cannot be modified or 
deleted. If clear, the key definition 
can be modified or deleted. 


The remaining bits are undefined and must be zero. It is possible to OR these 
values together to set more than one attribute at a time. 


equiv-string 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Character string to be substituted for the keystroke in the returned line. 
The equiv-string argument is the address of a descriptor pointing to this 
equivalence string. 


Equiv-string is echoed unless SMG$M_JCEY__NOECHO is set. If equiv- 
string is omitted, no equivalence string is defined for this key. 
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state-string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Contains a new state name which becomes the current state when this key is 
pressed. The state-string argument is the address of a descriptor pointing to 
the new state string. 

If omitted, no new state is defined. If the current state is temporary (that is, if 
SMG$M_KEY_LOCKSTATE was not specified for the most recently pressed 
defined key), the current state-string becomes the null string. 

DESCRIPTION 

SMG$ADD__KEY_DEF inserts a key definition into a key definition table. 

The table must have been created with a call to SMG$CREATE_KEY_TABLE. 
After SMG$ADD_KEY_DEF executes, the specified equivalence string is 
returned when the user types the specified key. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_PREDEFREP Successful completion. The previous key-definition 

has been replaced. 

SMG$_INVDEFATT Invalid key definition attributes. 

SMG$_INVKTB_ID Invalid key-table-id. 

SMG$_KEYDEFPRO Key definition is protected against change or 

deletion. 

SMG$_WRONUMARG Wrong number of arguments. 

Any condition values returned by LIB$COPY_DXDX. 
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SMG$ALLOW_ESCAPE—Allow Escape 



Sequences 

SMG$ALLOW_ESCAPE enables or disables SMG parsing of escape 
sequences which are output to a virtual display. 

FORMAT 

SMG$ALLOW—ESCAPE display-id , esc-flag 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Identifies the display in which output containing escape sequences is allowed. 
The display-id argument is the address of an unsigned longword that 
contains the display identifier. Display-id is returned by SMG$CREATE_ 
VIRTUAL-DISPLAY. 

esc-flag 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Determines whether escape sequence parsing is enabled or disabled. The 
esc-flag argument is the address of an unsigned longword that contains the 
escape flag. If esc-flag equals 1, parsing is on; if esc-flag equals 0, parsing is 
off. 

DESCRIPTION 

Normally, text written to a virtual display cannot contain escape sequences. 
SMG$ALLOW_ESCAPE lets escape sequences be interpreted as valid 
operations (for example, as a video attribute or a cursor positioning 
command). Thus, if esc-flag equals 1, the Screen Management Facility 
attempts to interpret the escape sequence and call the Screen Management 
routine that performs that function. If esc-flag equals 0, an error occurs if an 
escape sequence is detected. Note, however, that the virtual display must be 
pasted. 


Note: SMG$ALLOW_ESCAPE is intended to allow existing programs 

with embedded VT52/VT100 escape sequences to be converted to 
SMG$. SMG$ALLOW_ESCAPE should not be used in new program 
development. 


RTL-541 















Run-Time Library Routines 

SMG$ALLOW_ESCAPE 


CONDITION SS$_NORMAL 

VALUES SMGS—WRONUMARG 

RETURNED smg$_invdis_id 

SMG$_INVARG 


Normal successful completion. 
Wrong number of arguments. 
Invalid display-id. 

Invalid argument. 
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SMG$BEGIN_DISPLAY_UPDATE 
Begin Batching of Display Updates 

SMG$BEGIN_DISPLAY_UPDATE saves, or batches, all output 



to a virtual display until a matching call to SMG$END_DISPLAY_ 
UPDATE is encountered. 

FORMAT 

SMG$BEGIN_DISPLAY_UPDATE display-id 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display for which output is to be batched. The display-id 
argument is the address of an unsigned longword that contains the display 
identifier. 

Display-id is returned by SMG$CREATE_VIRTUAL-DISPLAY. 

DESCRIPTION 

SMG$BEGIN_DISPLAY—UPDATE lets you make more than one change to 
a display and have the changes appear only after all changes are complete. 
Thus, the user sees the display change from its initial state to its final state, 
without seeing any of the intermediate states. 

Batching terminates when SMG$END_DISPLAY—UPDATE has been called 
the same number of times as has SMG$BEGIN—DISPLAY—UPDATE for a 
given display. The Screen Management Facility keeps track of batching for a 
given display; thus, the calls to the SMG$BEGIN—DISPLAY—UPDATE and 
SMG$END_DISPLAY—UPDATE need not occur in the same module. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_BATWAS_ON Successful completion; note that batching had 

already been initiated. 

SMGS—WRONUMARG Wrong number of arguments. 

SMG$_INVDIS_ID Invalid display-id. 
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SMG$BEGIN_PASTEBOARD_UPDATE 
Begin Batching of Pasteboard Updates 

SMG$BEGIN_PASTEBOARD_UPDATE saves, or batches, all output 



to a pasteboard until a matching call to SMG$END_PASTEBOARD_ 
UPDATE is encountered. 

FORMAT 

SMG$BEGIN_PASTEBOARD_UPDATE 

pasteboard-id 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard for which output is to be batched. The pasteboard- 
id argument is the address of an unsigned longword that contains the 
pasteboard identifier. Pasteboard-id is returned by SMG$CREATE— 
PASTEBOARD. 

DESCRIPTION 

SMG$BEGIN_PASTEBOARD_UPDATE lets you make more than one 
change to a pasteboard and have the changes appear only after all changes 
are complete. Thus, the user sees the pasteboard change from its initial state 
to its final state, without seeing any of the intermediate states. 

Batching terminates when SMG$END_PASTEBOARD_UPDATE has been 
called the same number of times as has SMG$BEGIN—PASTEBOARD— 
UPDATE for a given pasteboard. The Screen Management Facility keeps 
track of batching for a given pasteboard; thus, the calls to the SMG$BEGIN_ 
PASTEBOARD_UPDATE and SMG$END_PASTEBOARD—UPDATE need 
not occur in the same module. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_BATWAS_ON Successful completion; note that batching had 

already been initiated. 

SMG$_WRONUMARG Wrong number of arguments. 

SMG$_INVPAS_ID Invalid pasteboard-id. 
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SMG$CANCEI_INPUT—Cancel Input 



Request 

SMG$CANCEI_INPUT immediately cancels any read-in-progress 

that was issued by SMG$READ_COMPOSED_LINE, SMG$READ_ 
KEYSTROKE, SMG$READ_STRING or SMG$READ_VERIFY. 

FORMAT 

SMGSCANCEL_INPUT keyboard-id 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

keyboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual keyboard for which the input is to be cancelled. The 
keyboard-id argument is the address of an unsigned longword that contains 
the keyboard identifier. Keyboard-id is returned by SMG$CREATE_ 

VIRTU AL—KEYBOARD. 

DESCRIPTION 

SMG$CANCEL_INPUT causes immediate termination of an SMG$READ_ 
COMPOSED-LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING or 
SMG$READ—VERIFY input operation from a terminal. The condition code 

SS$—ABORT is returned to those routines when you use SMG$CANCEL— 
INPUT. Note that if the specified virtual keyboard is associated with an 

RMS file, this procedure has no effect because it is not possible to cancel an 
outstanding RMS input operation. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_RMSNOTCAN Successful completion. RMS operation cannot be 

cancelled. 

SMG$_INVKBD_ID Invalid keyboard-id. 

SMG$_WRONUMARG Wrong number of arguments. 
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SMG$CHANGE_PBD_CHARACTERISTICS 
Change Pasteboard Characteristics 

SMG$CHANGE_PBD_CHARACTERISTICS lets you change the 



width, height, and background color associated with a pasteboard. 

FORMAT 

SMG$CHANGE_PBD_CHARACTERISTICS 

pasteboard-id [, desired-width] 

[, resulting-width] [, desired-height] 

[, resulting-height] [, desired- 
background-color] [, resulting- 
background-color] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

pasteboard-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard whose characteristics are to be changed. The 
pasteboard-id argument is the address of an unsigned longword that contains 
the pasteboard identifier. 

Pasteboard-id is returned by SMG$CREATE_PASTEBOARD. 

desired-width 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

New width for the pasteboard. The desired-width argument is the address 
of a signed longword integer that contains the desired width. If omitted, the 
width does not change. 

resulting- width 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Physical width of the pasteboard. The resulting-width argument is the 
address of a signed longword integer into which is written the actual width of 
the pasteboard. 
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Resulting-width may be larger than desired-width if the terminal cannot 
be set exactly to the desired-width. Resulting-width may be smaller 
than desired-width if the physical width of the terminal is smaller than 

desired-width. 


desired-height 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

New height for the pasteboard. The desired-height argument is the 
address of a signed longword integer that contains the desired height of the 
pasteboard. If omitted, the height does not change. 


resulting-height 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Physical height of the pasteboard. The resulting-height argument is the 
address of a signed longword integer into which is written the actual height 
of the pasteboard. 


Resulting-height may be larger than desired-height if the terminal cannot 
be set exactly to the desired-height. Resulting-height may be smaller 
than desired-height if the physical height of the terminal is smaller than 

desired-height. 


desired-background-color 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Symbolic name for the desired color. The desired-background-color 
argument is the address of an unsigned longword that contains the desired 
color. 


If omitted, the background color is not changed. Valid choices are SMG$C_ 
COLOR-WHITE and SMG$C_COLOR_BLACK. 


resulting-background-color 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Receives the actual color chosen. The resulting-background-color argument 
is the address of an unsigned longword into which is written the actual 
background color. If the terminal does not support the specified color, the 
nearest approximation is chosen. 

This routine may return SMG$C_COLOR—WHITE, SMG$C_COLOR- 
BLACK, or SMG$C_COLOR—UNKNOWN. If desired-background-color is 
omitted, the value of resulting-background-color does not change. 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


SMG$CHANGE_PBD_CHARACTERISTICS lets you change the width, 
height, and background color associated with a pasteboard. 


SS$_NORMAL 

SMG$_WRONUMARG 

SMG$_PBDIN_USE 

SMG$_INVWIDARG 

SMG$_INVPAGARG 

SMG$_INVCOLARG 


Normal successful completion. 

Wrong number of arguments. 

Cannot change characteristics while batching is on. 
Invalid width of 0 desired. 

Invalid height of 0 desired. 

Unknown background color specified. 
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SMG$CHANGE_RENDITION 
Change Default Rendition 

SMG$CHANGE_RENDITION changes the video attributes for all or 



part of a virtual display. 

FORMAT 

SMG$CHANGE_RENDITION 

display-id, start-row, start-col ,rows 
, columns [,rendition-set] 

[,rendition-complement] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display whose default rendition is to be changed. The 
display-id argument is the address of an unsigned longword that contains 
the display identifier. 

Display-id is returned by SMG$CREATE—VIRTU AI^DISPLAY. 

start-row 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Starting row position to receive the new rendition. The start-row argument 
is the address of a signed longword integer that contains the number of the 
starting row. 

start-col 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Starting column position to receive the new rendition. The start-col argument 
is the address of a signed longword integer that contains the number of the 
starting column. 
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rows 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Number of rows to receive the new rendition. The rows argument is the 
address of a signed longword integer that contains the number of rows to be 
affected. 


columns 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Number of columns to receive the new rendition. The columns argument is 
the address of a signed longword integer that contains the number of columns 
to be affected. 


rendition-set 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mask which denotes video attributes for the specified portion of the virtual 
display. The rendition-set argument is the address of an unsigned longword 
whose bits control the video rendition. Each bit in this argument affects the 
corresponding attribute in the display. 

Video attributes which can be manipulated in this manner are as follows: 


SMG$M_BLINK 

SMG$M_BOLD 

SMG$M_REVERSE 

SMG$M_UNDERLINE 


Displays blinking characters 

Displays characters in higher-than-normal intensity 

Displays characters in reverse video, that is, using 
the opposite default rendition of the virtual display 

Displays underlined characters 


The rendition-set/rendition-complement scheme works as follows: 

• Each display has a default rendition associated with it when it is created. 

• When SMG$CHANGE_RENDITION is called, each bit in the default 
rendition set is ORed (the Boolean OR operation) with the corresponding 
bit in the rendition-set argument. 

• The result of this operation is then XORed (the Boolean EXCLUSIVE OR 
operation) with each bit in the rendition-complement argument. 

Using these two arguments, the caller can exercise independent control over 

each attribute in a single call. 
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rendition-complement 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mask which denotes video attributes for the specified portion of the virtual 
display. The rendition-complement argument is the address of an unsigned 
longword whose bits control the video rendition. 

Each bit in rendition-complement affects the corresponding attribute in the 
display. Video attributes which can be manipulated in this manner are the 
same as for the rendition-set argument. 

The following table shows the action taken by the Screen Management 
Facility for various combinations of rendition-set and rendition-complement 
attributes: 


Set 

Complement 

Action 

0 

0 

Attribute unchanged 

1 

0 

Attribute on 

0 

1 

Attribute set to complement of default setting 

1 

1 

Attribute off 


DESCRIPTION This procedure changes the default video rendition of a rectangular block of 

text already in the specified virtual display. For example, you might use this 
procedure to redisplay a particular row in reverse video. 


CONDITION SS$_NORMAL 

VALUES SMG$_NO_CHADIS 

RETURNED 

SMGS—INVROW 

SMG$_INVCOL 

SMG$_INVDIS_ID 

SMG$_INVARG 

SMG$_WRONUMARG 


Normal successful completion. 

Successful completion. No change to virtual 
display. 

Invalid start row. The specified row is outside the 
virtual display. 

Invalid start column. The specified column is 
outside the virtual display. 

Invalid display-id. 

Invalid number of rows, invalid number of columns, 
unrecognized rendition-set code, or unrecognized 
rendition-complement code. 

Wrong number of arguments. 
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SMG$CHANGE_VIRTUAI_DISPLAY 

Change Virtual Display 


SMG$CHANGE_VIRTUAI_DISPLAY lets you change the 

dimensions, border, and video attributes of a virtual display. 

FORMAT 

SMG$CHANGE_VIRTUAI_DISPLAY 

display-id ,rows, columns [, display- 
attributes] [, video-attributes] [, char¬ 
set] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display whose attributes are to be changed. The display- 
id argument is the address of an unsigned longword that contains the display 
identifier. 

Display-id is returned by SMG$CREATE—VIRTUAL—DISPLAY. 


rows 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the new number of rows for the virtual display. The rows argument 
is the address of a signed longword integer that contains the number of rows 
in the virtual display. 


columns 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the new number of columns for the virtual display. The columns 
argument is the address of a signed longword integer that contains the 
number of columns in the virtual display. 
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display-attributes 


VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies whether the virtual display is bordered (the default). The display- 
attributes argument is the address of an unsigned longword that contains the 
display attributes mask. 


To explicitly specify a bordered display, use the mask SMG$M_BORDER. All 
other bits are reserved for use by DIGITAL and must be zero. 


video-attributes 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the default rendition to be applied to all output in a virtual display, 
unless overridden by a call to a specific output routine. The video-attributes 
argument is the address of an unsigned longword that contains the video 
attributes mask. 


For example, a call to SMG$PUT_CHARS with an explicit rendition specified 
would override the default rendition. 


The bits that can be set for this argument are as follows: 


SMG$M_BLINK 

SMG$M_BOLD 

SMG$M_REVERSE 

SMG$M_UNDERLINE 


Sets the display default to blinking characters 

Sets the display default to characters in higher- 
than-normal intensity 

Sets the display default to characters in reverse 
video, that is, to the opposite of the current default 
rendition of the virtual display 

Sets the display default to underlined characters 


Note that you can specify any combination of attributes in a single call. All 
other bits are reserved for use by DIGITAL and must be zero. 


char-set 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the default character set for all text in this virtual display. The 
char-set argument is the address of an unsigned longword that contains the 

character set specifier. At this time, the only valid value is SMG$C_ASCII, 

which is also the default. 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


SMG$CHANGE_VIRTUAL-DISPLAY lets you change the size or default 
attributes of an existing virtual display. If the size of the virtual display 
is changed, the Screen Management Facility attempts to remap the text 
associated with the display to fit the new dimensions (starting at row and 
column 1). If the new size of the virtual display is smaller than the old size, 
text may be truncated. If the new size of the virtual display is larger than the 
old size, text may be padded on the right with spaces. 

When a display is redimensioned, the virtual cursor for the display is moved 
to row 1 and column 1. Note that if a labeled border applies to the virtual 
display and does not fit the redimensioned display, the label is deleted. 


SS$_NORMAL 

LIB$_INSVIRMEM 

SMGS—INVARG 

SMG$_WRONUMARG 

SMG$_INVDIS_ID 


Normal successful completion. 

Insufficient virtual memory to reallocate needed 
buffers. 

Invalid video or display attributes. 

Wrong number of arguments. 

Invalid display-id. 
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SMG$CHECK_ 

FOR—OCCLUSION 

SMG$CHECK_FOR—OCCLUSION 
Check For Occlusion 



SMG$CHECK_FOR_OCCLUSION checks to see whether a virtual 
display is covered by another virtual display. 

FORMAT 

SMG$CHECK_FOR_OCCLUSION 

display-id 
, pasteboard-id 
,occ!usion-state 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 



ARGUMENTS display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display to be checked. The display-id argument is 
the address of an unsigned longword that contains the display identifier. 
Display-id is returned by SMG$CREATE—VIRTUAL —DISPLAY. 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard to be checked. The pasteboard-id argument is the 
address of an unsigned longword that contains the pasteboard identifier. 
Pasteboard-id is returned by SMG$CREATE —PASTEBOARD. 

occlusion-state 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Receives the value denoting whether the display is occluded. The occlusion- 
state argument is the address of a signed longword integer into which the 
occlusion state is written. Occlusion-state is set to 1 if the display is occluded 
or set to 0 if the display is not occluded on the specified pasteboard. If the 
procedure does not return SS$_NORMAL, the contents of occlusion-state are 
undefined. 
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DESCRIPTION 

SMG$CHECK_FOR_OCCLUSION determines whether a specified virtual 
display (as pasted to the specified pasteboard) is occluded, or covered up, by 
another virtual display. 

CONDITION 

SS$_NORMAL 

Normal successful completion. 

VALUES 

SMG$_NOTPASTED 

Specified virtual display is not pasted to the 

RETURNED 


specified pasteboard. 


SMG$_INVPAS_ID 

Invalid pasteboard-id. 


SMG$_WRONUMARG 

Wrong number of arguments. 


SMG$_INVDIS_ID 

Invalid display-id. 


EXAMPLE 


C+ 

C This FORTRAN example program demonstrates the use of 
C SMG$CHECK_FOR_OCCLUSION. 

C 

C This routine creates a virtual display and writes it to the 
C pasteboard. Data is placed in the virtual display via SMG$PUT_CHARS. 
C- 


INTEGER SMG$CREATE_VIRTUAL_DISPLAY, 
INTEGER SMG$PASTE_VIRTUAL_DISPLAY, 
INTEGER SMG$CHECK_FOR_OCCLUSION 
INTEGER DISPLAY1, DISPLAY2, PASTE1, 
INTEGER OCCLUSION. STATUS 
CHARACTER*29 TEXT 


SMG$CREATE_PASTEBOARD 

SMG$PUT_CHARS 

PASTE2, ROWS. COLUMNS. BORDER 


C+ 

C Include the SMG definitions. In particular, we want SMG$M_BORDER. 
C- 

INCLUDE '($SMGDEF)' 


C+ 

C Create two virtual displays using SMG$CREATE_VIRTUAL_DISPLAY. 
C Give them borders. 

C- 

ROWS = 6 
COLUMNS = 50 

STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS. COLUMNS. DISPLAY1. SMG$M_BORDER) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(y.VAL(STATUS)) 

ROWS = 5 
COLUMNS = 30 

STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS, COLUMNS. DISPLAY2, SMG$M_BORDER) 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 

C+ 

C Create the pasteboard using SMG$CREATE_PASTEBOARD. 

C- 


STATUS = SMG$CREATE_PASTEBOARD (PASTED 
IF (.NOT. STATUS) CALL LIB$SIGNAL(7.VAL(STATUS)) 
STATUS = SMG$CREATE_PASTEBOARD (PASTE2) 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 


C+ 

C Use SMG$PUT_CHARS to put data into the virtual displays. 
C- 


STATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 1 This virtual display has 6 rows and 50 columns. 1 , 2, 1) 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 
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STATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This is a bordered virtual display.', 3, 1) 

IF (.NOT. STATUS) CALL LIBlSIGNAL ('/.VAL (STATUS) ) 

STATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' SMG$PUT_CHARS puts data in this virtual display.', 4, 

1 1) 

IF (.NOT. STATUS) CALL LIBlSIGNAL ('/.VAL (STATUS) ) 

STATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This text should be partially occulded.', 5, 1) 

IF (.NOT. STATUS) CALL LIBlSIGNAL ('/.VAL (STATUS) ) 

STATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' So should part of this row.', 6, 1) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(7.VAL(STATUS)) 

STATUS = SMGIPUT.CHARS ( DISPLAY2, • This is virtual', 3, 1) 

IF (.NOT. STATUS) CALL LIBlSIGNAL ('/.VAL (STATUS) ) 

STATUS = SMGIPUT.CHARS ( DISPLAY2, 

1 ' display #2.',4,1) 

IF (.NOT. STATUS) CALL LIBlSIGNAL ('/.VAL (STATUS) ) 

STATUS = SMGIPUT.CHARS ( DISPLAY2, 

1 ' This is just some more text.', 5, 1) 

IF (.NOT. STATUS) CALL LIBlSIGNAL ('/.VAL (STATUS) ) 

Use SMGIPASTE.VIRTUAL.DISPLAY to paste the virtual display. 

C- 

STATUS = SMGIPASTE.VIRTUAL.DISPLAY ( DISPLAY1, PASTE1, 4, 15) 
IF (.NOT. STATUS) CALL LIBlSIGNAL ('/.VAL (STATUS) ) 

STATUS * SMGIPASTE.VIRTUAL.DISPLAY ( DISPLAY2, PASTE2, 8, 15) 
IF (.NOT. STATUS) CALL L IBIS I GNAL(‘/.VAL ( STATUS ) ) 

C+ 

C Check the two virtual displays for occlusion by calling 
C SMGICHECK.FOR.OCCLUSION. 

C- 


TEXT = 'This display is not occluded.' 

STATUS = SMGICHECK.FOR.OCCLUSION (DISPLAY1, PASTE1, OCCLUSION) 
IF (.NOT. STATUS) CALL LIBlSIGNAL ('/.VAL (STATUS) ) 

IF (OCCLUSION .EQ. 0) THEN 

STATUS = SMGIPUT.CHARS (DISPLAY1. TEXT, 1, 1) 

IF (.NOT. STATUS) CALL LIBlSIGNAL ('/.VAL (STATUS) ) 

ELSE 

STATUS = SMGIPUT.CHARS (DISPLAY1, 'Occluded.', 1 , 1) 
IF (.NOT. STATUS) CALL LIBlSIGNAL(7.VAL(STATUS)) 

END IF 

STATUS = SMGICHECK.FOR.OCCLUSION (DISPLAY2, PASTE2, OCCLUSION) 
IF (.NOT. STATUS) CALL LIBlSIGNAL ('/.VAL (STATUS) ) 

IF (OCCLUSION .EQ. 0) THEN 

STATUS = SMGIPUT.CHARS (DISPLAY2, TEXT, 1, 1) 

IF (.NOT. STATUS) CALL LIBlSIGNAL(7.VAL(STATUS)) 

ELSE 

STATUS = SMGIPUT.CHARS (DISPLAY2, 'Occluded.', 1,1) 
IF (.NOT. STATUS) CALL LIBlSIGNAL ('/.VAL (STATUS)) 

END IF 
END 


The output generated by this FORTRAN program is shown in Figure RTL-9. 
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Figure RTL-9 Output generated by FORTRAN Program Calling 
SMG$CHECK_FOR_OCCLUSION 
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SMG$COIMTROL_MODE—Control Mode 

SMG$CONTROL_MODE controls the mode of the pasteboard. This 
includes buffering, minimal updating, whether the screen is cleared 
when the pasteboard is deleted, and whether tab characters are 
used for screen formatting. 


FORMAT 

SMG$CONTROI_MODE 

pasteboard-id 
[, new-mode] [, old-mode] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 

pasteboard-id 



VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 



Specifies the pasteboard to be changed. The pasteboard-id argument is the 
address of an unsigned longword that contains the pasteboard identifier. 
Pasteboard-id is returned by SMG$CREATE_PASTEBOARD. 


new-mode 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the new control settings to be used. The new-mode argument is the 
address of an unsigned longword that contains the mode settings. A bit set to 
1 forces that mode to be employed while a bit set to 0 inhibits that mode of 
operation. 


Valid settings are as follows: 


SMG$M_BUF_ENABLED 

SMG$M_MINUPD 

SMG$M_CLEAR_SCREEN 

SMG$M_NOT ABS 


Enables buffering. 

Enables minimal update. 

Causes the Screen Management Facility to clear 
the screen when the program exits if you have not 
previously deleted the pasteboard. 

Causes the Screen Management Facility not to use 
tab characters to format the screen. 


All other bits must be zero and are reserved for future use by DIGITAL. 
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old-mode 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Receives the control settings that were in effect prior to calling this procedure. 
The old-mode argument is the address of an unsigned longword into 
which is written the former mode settings. A bit set to 1 indicates that 
the specified mode was employed while a bit set to 0 indicates that the mode 
was inhibited. 


DESCRIPTION SMG$CONTROL_MODE lets you interrogate and change the modes of the 
Screen Management Facility operation for a specified pasteboard. This routine 
has two optional parameters, new-mode and old-mode. By specifying 
different combinations of these arguments, SMG$CONTROL_MODE can be 
used in various ways. 

• To use SMG$CONTROL_MODE to determine the current mode settings, 
use the following format: 

SMG$CONTROL_MODE (pasteboard__id „old_mode) 

• To use SMG$CONTROL_MODE to set the bits without regard to their 
current setting, use the following format: 

SMG$CONTROL_MODE (pasteboard_id ,new_mode) 


• To use SMG$CONTROL__MODE to save the current settings, set new 
modes, and later restore the original settings, use the following format: 

SMG$CONTROL_MODE (pasteboard_id ,new_mode ,save_old_ 
settings) 

This retrieves the current bit settings and then sets the mode according to 
the new-mode argument. 

Later, to restore the mode to its former state, specify the following format: 
SMG$CONTROL_MODE (pasteboarcLid ,save_old_settings) 

This sets the new mode setting according to those previously retrieved. 

Note that if both arguments are omitted, no information is returned. 

The modes that can be interrogated and changed using SMG$CONTROL_ 
MODE are as follows: 

Buffering 

In this mode, the Screen Management Facility buffers all output for efficient 
use of system QIOs. By calling SMG$FLUSH_BUFFER, the user can force to 
the screen any output that has been placed in the pasteboard buffer but not 
yet written to the terminal. 

Minimal Screen Update 

By default, the Screen Management Facility tries to minimize the number of 
characters actually sent to the terminal. It does this by sending only those 
characters that have changed. 
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Nonminimal updating rewrites any line containing a change, starting with the 
first changed character on that line. 

Clear Screen 

By default, the Screen Management Facility clears the screen when the 
program exits if you have not already deleted the pasteboard. To prevent this 
default behavior, turn the clear screen bit off. 


No Tabs 


If this bit is set, the Screen Management Facility does not rely on the 
terminal's tab settings. If it is not set, the Screen Management Facility 
will use physical tabs for the minimal update procedure. However, note that 
such use implicitly assumes that the tab stops are set to the DIGITAL default 
locations. Specify "no tabs" if you want to be sure that the application will 
run regardless of the tab settings the user has set on the terminal. By default, 
this bit is clear. 


CONDITION 

VALUES 

RETURNED 


SSS—NORMAL 

SMG$_INVARG 


Invalid argument. New-mode has a bit set which 
does not correspond to SMG$M_BUF_ENABLED, 
SMG$M_MINUPD, SMG$M_CLEAR_SCREEN, or 
SMG$M_NOT ABS. 


Normal successful completion. 


SMG$_INVPAS_ID 

SMG$_WRONUMARG 


Wrong number of arguments. 


Invalid pasteboard-id. 
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SMG$COPY_VIRTUAL-DISPLAY—Copy a 

Virtual 

Display 



SMG$COPY_VIRTUAL—DISPLAY creates a copy of an existing 
virtual display and assigns to it a new virtual display number. 

FORMAT 

SMG$COPY_VIRTUAI_DISPLAY curr-display-id 

, ne w-displa y-id 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

curr-display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display identifier of the virtual display to be replicated. The curr-display-id 
argument is the address of the unsigned longword that contains the display 
identifier. 

new-display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Receives the display identifier of the newly created virtual display. The new- 
display-id argument is the address of the unsigned longword that receives 
the new display identifier. 

DESCRIPTION 

SMG$COPY_VIRTUAL—DISPLAY creates a copy of an existing virtual 
display and assigns to it a new virtual display number. This newly created 
virtual display will not be pasted anywhere; use SMG$PASTE—VIRTUAL _ 
DISPLAY and the new-display-id identifier to paste the newly created virtual 
display. The existing display being replicated does not have to be pasted 
when SMG$COPY_VIRTUAL-DISPLAY is invoked. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

LIB$_INSVIRMEM Insufficient virtual memory to allocate needed 

buffer. 
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EXAMPLE 


O 

C This FORTRAN example program demonstrates the use of 
C SMG$COPY_VIRTUAL_DISPLAY. 

C 

C This routine creates a virtual display and writes it to the 
C pasteboard. Data is placed in the virtual display via SMG$PUT_CHARS. 
C- 

IMPLICIT INTEGER (A-Z) 

CHARACTER*29 TEXT 

C+ 

C Include the SMG definitions. In particular, we want SMG$M_BORDER. 

C- 

INCLUDE '($SMGDEF)' 

C+ 

C Create two virtual displays using SMG$CREATE_VIRTUAL_DISPLAY. 

C Give them borders. 

C- 

ROWS = 6 
COLUMNS = 50 

STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS, COLUMNS. DISPLAY1, SMG$M_BORDER) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(*/.VAL(STATUS)) 

ROWS = 5 
COLUMNS = 30 

STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS, COLUMNS. DISPLAY2, SMG$M_BORDER) 

IF (.NOT. STATUS) CALL LIBISIGNAL(%VAL(STATUS)) 

C+ 

C Create the pasteboard using SMG$CREATE_PASTEBOARD. 

C- 

STATUS = SMG$CREATE_PASTEBOARD (PASTED 
IF (.NOT. STATUS) CALL LIBISIGNAL(%VAL(STATUS)) 

STATUS = SMGlCREATE.PASTEBOARD (PASTE2) 

IF (.NOT. STATUS) CALL LIBISIGNAL C/.VAL (STATUS) ) 

C+ 

C Use SMG$PUT_CHARS to put data into the virtual displays. 

C- 

STATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This virtual display has 6 rows and 50 columns.', 2, 1) 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 

STATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This is a bordered virtual display.', 3, 1) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(7.VAL(STATUS)) 

STATUS = SMG$PUT_CHARS ( DISPLAYi, 

1 ' SMG$PUT_CHARS puts data in this virtual display.', 4, 

1 1) 

IF (.NOT. STATUS) CALL LIBISIGNAL(%VAL(STATUS)) 

STATUS = SMG$PUT_CHARS ( DISPLAYI, 

1 ' This text should be partially occluded.', 5, i) 

IF (.NOT. STATUS) CALL LIBISIGNAL OiVAL(STATUS)) 

STATUS = SMG$PUT_CHARS ( DISPLAYI. 
i ' So should part of this row.', 6, 1) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(7.VAL(STATUS)) 

STATUS * SMG$PUT_CHARS ( DISPLAY2, ' This is virtual', 3, 1) 

IF (.NOT. STATUS) CALL LIBISIGNAL(%VAL(STATUS)) 

STATUS = SMG$PUT_CHARS ( DISPLAY2, 

1 ' display #2.', 4, i) 

IF (.NOT. STATUS) CALL L IBIS I GNAL(*/.VAL( STATUS ) ) 

STATUS = SMG$PUT_CHARS ( DISPLAY2, 

1 ' This is just some more text.', 5, 1) 

IF (.NOT. STATUS) CALL LIBISIGNAL C/.VAL (STATUS) ) 
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C+ 

C Use SMG$PASTE_VIRTUAI._DISPLAY to paste the virtual display. 

C- 

* STATUS * SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15) 

IF (.NOT. STATUS) CALL LIB$SIGNAL('/.VAL(STATUS)) 

STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY2, PASTE2, 8, 15) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(7.VAL(STATUS)) 

C+ 

C Copy the first virtual display, the one that is partially occluded. 

C- 

STATUS = SMG$COPY_VIRTUAL_DISPLAY ( DISPLAY1, NEW.DISPLAY) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(y, VAL (STATUS)) 

C+ 

C Now paste this new virtual display so that it occludes the other displays. 
C- 


STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( NEW.DISPLAY, PASTE1, 4, 20) 
IF (.NOT. STATUS) CALL LIB$SIGNAL(7.VAL(STATUS)) 

END 


The first virtual display created by this FORTRAN example is shown in Figure 
RTL-9.1. 

Figure RTL-9.1 First Virtual Display Generated by This Example 
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The second virtual display created by this FORTRAN example is shown in 
Figure RTL-9.2. 
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Figure RTL-9.2 Second Virtual Display Generated by This 
Example 
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The output generated after the call to SMG$COPY_VIRTUAL—DISPLAY is 
shown in Figure RTL-9.3. 

Figure RTL-9.3 Output Generated After the Call to 
SMG$COPY_VIRTUAL—DISPLAY 
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SMG$CREATE_KEY_TABLE—Create Key 

Table 



SMG$CREATE_KEY_TABLE creates a table for key definitions. 

FORMAT 

SMG$CREATE_KEY_TABLE new-key-table-id 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

new-key-table-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Receives the identifier of the newly-created key table. The new-key-table-id 
argument is the address of an unsigned longword into which is written the 
key table identifier. 

DESCRIPTION 

SMG$CREATE_KEY—TABLE creates a key definition table. Key definitions 
can then be added to this table with the SMG$ADD_KEY—DEF, 
SMG$LOAD_KEY_DEFS and SMG$DEFINE_KEY routines. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_WRONUMARG Wrong number of arguments. 

LIB$_INSVIRMEM Insufficient virtual memory. 
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SMG$CREATE_PASTEBOARD 
Create Pasteboard 



SMG$CREATE_PASTEBOARD creates a pasteboard and returns its 
assigned pasteboard-id. 

FORMAT 

SMG$CREATE_PASTEBOARD 

new-pasteboard-id 
[, output-device] 

[,pb-rows] [,pb-columns] 

[, preserve-screen-flag] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

new-pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Receives the identifier of the newly created pasteboard. The new-pasteboard- 
id argument is the address of an unsigned longword into which is written the 
new pasteboard identifier. 

output-device 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Specifies the file specification or logical name to which the output associated 
with this pasteboard will be written. The output-device argument is the 
address of a descriptor that points to the name of the output device. If 
omitted, output is sent to SYSSOUTPUT. 

pb-rows 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Receives the number of rows on the device specified in the output-device 
argument. The pb-rows argument is the address of a signed longword integer 
into which is written the number of rows on the specified device. 
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pb-columns 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Receives the number of columns on the device specified in the output-device 
argument. The pb-columns argument is the address of a signed longword 
integer into which is written the number of columns on the specified device. 


preserve-screen-flag 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies whether the screen is cleared before the Screen Management 
Facility performs any output to it. The preserve-screen-flag argument is the 
address of an unsigned longword that contains the screen preservation flag. 
If preserve-screen-flag is set to 0, the screen is initially cleared; if set to 1, 
the screen is not initially cleared. The default action is to clear the screen. 
The Screen Management Facility works best when it can manage the entire 
screen. Therefore, setting this flag to 1 is discouraged. 


DESCRIPTION 

SMG$CREATE_PASTEBOARD creates a new pasteboard and returns its 
assigned pasteboard-id. Note that if you request a pasteboard on a device 
which already has a pasteboard assigned, this routine returns the pasteboard- 
id of the existing pasteboard and returns the SMG$_PASALREXI status code. 
Modularity considerations dictate that if the pasteboard already exists, you 
must not delete it. 

CONDITION 

SS$_NORMAL 

Normal successful completion. 

VALUES 

SMG$_PASALREXI 

Successful completion. A pasteboard already 

RETURNED 


exists for this device. 


LIB$_INSVIRMEM 

Insufficient virtual memory. 


SMG$_WRONUMARG 

Wrong number of arguments. 


EXAMPLES 

a 


0I1I2I3I4I5I6I7I 

12346678901234567890123466789012345678901234567890123456789012346678901234667890 


c 

CREPAS 

EXTRN'SMG$CREATE_PASTEBOARD' 

c 

CREDIS 

EXTRN'SMG$CREATE_VIRTUAL_DISPLAY 

c 

PUTCHA 

EXTRN'SMG$PUT_CHARS' 



c 

PASDIS 

EXTRN'SMG$PASTE_VIRTUAL_DISPLAY 1 

c 


Z-ADD0 

ZERO 

90 


c 


Z-ADD1 

LINCOL 

90 


c 


Z-ADD2 

LINE 

90 


c 


Z-ADD5 

COLUMN 

90 


c 


MOVE 'Menu' 

OUT 

4 


c* 

Create the pasteboard. 




c 


CALL CREPAS 




c 


PARM 

PASTID 

90 

WL 

c 


PARMV 

ZERO 



c 


PARM 

HEIGHT 

90 

WL 

c 


PARM 

WIDTH 

90 

WL 
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C* Create 

the 

virtual display. 



C 


CALL CREDIS 



C 


PARM 

HEIGHT 

RL 

C 


PARM 

WIDTH 

RL 

C 


PARM 

DISPID 

90 WL 

C* Output 

the 

'Menu'. 



C 


CALL PUTCHA 



C 


PARM 

DISPID 

RL 

C 


PARMD 

OUT 


C 


PARM 

LINE 

RL 

C 


PARM 

COLUMN 

RL 

C* Paste the 

virtual display. 



C 


CALL PASDIS 



C 


PARM 

DISPID 

RL 

C 


PARM 

PASTID 

RL 

C 


PARM 

LINCOL 

RL 

C 


PARM 

LINCOL 

RL 

C 


SETON 


LR 


The RPG II program above displays 'Menu' beginning at line 2, column 5. 

C+ SMGl.FOR 

C This FORTRAN exmaple program demonstrates how to use 
C SMG$CREATE_PASTEBOARD. 

C- 

IMPLICIT INTEGER*4 (A-Z) 

SMG$M_B0LD = 1 
SMG$M_REVERSE = 2 
SMG$M_BLINK = 4 
SMG$M_UNDERLINE = 8 
C+ 

C Establish the terminal screen as a pasteboard 
C by calling SMG$CREATE_PASTEBOARD. 

C- 


STATUS = SMG$CREATE_PASTEBOARD (NEW.PID,,,) 

IF (.NOT. STATUS) CALL LIB$STOP(ftVAL(STATUS)) 
C+ 

C Establish a virtual display region by calling 
C SMG$CREATE_VIRTUAL_DISPLAY. 

C- 


STATUS * SMG$CREATE_VIRTUAL.DISPLAY (5,80.DISPLAY.ID,.,) 
IF (.NOT. STATUS) CALL LIB$STOP(XVAL(STATUS)) 

C+ 

C Paste the virtual display to the screen, starting at 
C row 10, column 15 using SMG$PASTE_VIRTUAL_DISPLAY. 

C- 


STATUS = SMG$PASTE_VIRTUAL_DISPLAY(DISPLAY.ID,NEW.PID,10,15) 
IF (.NOT. STATUS) CALL LIBlSTOPOiVAL(STATUS)) 

C+ 

C Write three lines to the screen using SMG$PUT_LINE. 

C- 


STATUS = SMG$PUT_LINE (DISPLAY.ID.'This line is underlined',2, 

1 SMG$M_UNDERLINE,0.,) 

IF (.NOT. STATUS) CALL LIB$ST0POiVAL(STATUS)) 

STATUS = SMG$PUT_LINE (DISPLAY.ID.'This line is blinking'.2, 

1 SMG$M_BLINK,0,,) 

IF (.NOT. STATUS) CALL LIBlSTOP (7.VAL (STATUS)) 

STATUS = SMG$PUT_LINE (DISPLAY.ID,'This line is reverse video',2, 
1 SMG$M_REVERSE,0,,) 

IF (.NOT. STATUS) CALL LIB$ST0P(%VAL(STATUS)) 

END 


This FORTRAN program calls Run-Time Library Screen Management routines 
to format screen output. 
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SMG$CREATE_VIRTUAI_DISPLAY 

Create Virtual Display 

SMG$CREATE_VIRTUAI_DISPLAY creates a virtual display and 



returns its assigned display id. 

FORMAT 

SMG$CREATE_VIRTUAI_DISPLAY 

num-rows, num-columns, new- 
display-id [, display-attributes] 

[, video-attributes] [, char-set] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

num-rows 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the number of rows in the newly created virtual display. The 
num-rows argument is the address of a signed longword integer that contains 
the desired number of rows. 

num-columns 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the number of columns in the newly created virtual display. The 
num-columns argument is the address of a signed longword integer that 
contains the desired number of columns. 

new-display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Receives the display-id of the newly created virtual display. The display-id 
argument is the address of an unsigned longword into which is written the 
display identifier. 
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display-attributes 


VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies whether the virtual display is bordered (the default is no border). 
The display-attributes argument is the address of an unsigned longword that 
contains the display attributes mask. 


To specify a bordered display, use the mask SMG$M_BORDER. If omitted, 
the display is not bordered. Two other display attributes may also be 
specfied. If SMG$M_TRUNC_ICON is specified, an icon (generally a 
diamond shape) is displayed where truncation has occured by exceeding the 
dimensions of the virtual display. When SMG$M_DISPLAY_CONTROLS is 
used, control characters such as carriage return and line feed are displayed as 
characters ( <CR> <LF> ) so that you can easily see where they are. 


video-attributes 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the default rendition to be applied to all output in this virtual 
display unless overridden by a call to a specific output routine (for example, 
SMG$CHANGE_RENDITION). The video-attributes argument is the 
address of an unsigned longword that contains the video attributes mask. 

Allowed values for this argument are as follows: 


SMG$M_BLINK 
SMG$M_BOLD 
SMG$M_RE VERSE 

SMG$M_UNDERLINE 


Displays blinking characters 

Displays characters in higher-than-normal intensity 

Displays characters in reverse video, that is, using 
the opposite default rendition of the virtual display 

Displays underlined characters 


char-set 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the default character set for all text in this virtual display. The 
char-set argument is the address of an unsigned longword that contains the 
character set specifier. At this time, the only valid value is SMG$C_ASCII, 
which is also the default. 


DESCRIPTION SMG$CREATE_VIRTUAL-DISPLAY creates a new virtual display and 

returns its display id. Initially, the virtual display contains blanks, and the 
virtual cursor is positioned at row 1, column 1. 
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CONDITION 

VALUES 

RETURNED 


SSS—NORMAL 

LIB$_INSVIRMEM 

SMG$_INVARG 

SMG$_WRONUMARG 


Normal successful completion. 

Insufficient virtual memory. 

Invalid argument. Video-attributes or display- 
attributes contains an unknown value. 

Wrong number of arguments. 


EXAMPLES 


C This FORTRAN example program demonstrates how to use 
C SMG$CREATE_VIRTUAL_DISPLAY. 

C- 

IMPLICIT INTEGERS (A-Z) 

CHARACTER * 80 OUT_STR.TRIM.STR 

CHARACTER*18 PROMPT /'Please enter data '/ 

SMGIM.BOLD = 1 
SMG$M_REVERSE = 2 
SMG$M_BLINK = 4 
SMG$M_UNDERLINE = 8 
C+ 

C Establish the terminal keyboard as the virtual keyboard 
C by calling SMG$CREATE_VIRTUAL_KEYBOARD. 

C- 


STATUS = SMG$CREATE_VIRTUAL_KEYBOARD(KEYBOARD.ID,,,) 
IF (.NOT. STATUS) CALL LIB$ST0PC/.VAL(STATUS)) 

C+ 

C Establish the terminal screen as a pasteboard using 
C SMG$CREATE_PASTEBOARD. 

C- 


STATUS = SMG$CREATE_PASTEBOARD (NEW.PID,,,) 

IF (.NOT. STATUS) CALL LIB$ST0P(7.VAL(STATUS)) 

C+ 

C Establish a virtual display region by 
C calling SMG$CREATE_VIRTUAL_DISPLAY. 

C- 

STATUS = SMG$CREATE_VIRTUAL_DISPLAY (5,80,DISPLAY_ID,.,) 

IF (.NOT. STATUS) CALL LIB$ST0P(7.VAL(STATUS)) 

C+ 

C Paste the virtual display to the screen, starting at 
C row 10, column 15. To paste the virtual display, use 
C SMGlPASTE.VIRTUAL.DISPLAY. 

C- 

STATUS = SMG$PASTE_VIRTUAL_DISPLAY(DISPLAY.ID,NEW.PID,10,15) 
IF (.NOT. STATUS) CALL LIB$ST0P(7.VAL(STATUS)) 

C+ 

C Prompt the user for input, and accept that input using 
C SMG$READ_STRING. 

C- 


STATUS = SMGIREAD.STRING(KEYBOARD.ID,OUT.STR,PROMPT.,,,,,,) 
IF (.NOT. STATUS) CALL LIB$ST0P(7.VAL(STATUS)) 

C+ 

C Clear the screen using SMG$ERASE_PASTEBOARD. 

C- 


STATUS = SMG$ERASE_PASTEBOARD (NEW.PID) 

IF (.NOT. STATUS) CALL LIB$ST0P (7.VAL (STATUS) ) 
C+ 

C Trim any trailing blanks from the user input 
C by calling STR$TRIM. 

C- 

STATUS = STR$TRIM(TRIM.STR,OUT.STR,STR.LEN) 

IF (.NOT. STATUS) CALL LIB$ST0P (*/.VAL (STATUS) ) 


C+ 
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C Display the data input by the user using SMG$PUT_CHARS 
C and SMG$PUT_LINE. 

C- 


STATUS * SMG$PUT_CHARS(DISPLAY_ID,'You entered: 

IF (.NOT. STATUS) CALL LIB$STOPC/.VAL(STATUS)) 

STATUS = SMG$PUT_LINE(DISPLAY_ID,TRIM_STR(1:STR_LEN),, 
i SMG$M_REVERSE,0,,) 

IF (.NOT. STATUS) CALL LIB$STOP(Y.VAL(STATUS)) 

END 


The output generated by this FORTRAN example is shown in Figure RTL-10. 


Figure RTL—10 Output of FORTRAN Program Calling 
SMG$CREATE_VIRTUAI_DISPLAY 
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For an example of calling SMG$CREATE_VIRTUAL-DISPLAY in RPG, see 
the example in the description of SMG$CREATE—PASTEBOARD. 
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SMG$CREATE_VIRTUAI_KEYBOARD 

Create Virtual Keyboard 



SMG$CREATE_VIRTUAI_KEYBOARD creates a virtual keyboard 

and returns its assigned keyboard-id. 

FORMAT 

SMG$CREATE_VIRTUAI_KEYBOARD 

new-keyboard-id [, filespec] 

[, default-filespec] [, resultant-filespec] 
[,recall-size] 

RETURNS 

VMS Usage: cond-value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

new-keyboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Receives the keyboard identifier of the newly created virtual keyboard. The 
new-keyboard-id argument is the address of an unsigned longword into 
which is written the keyboard identifier. 

filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String containing the file specification or logical name of the file or terminal 
to be used for this virtual keyboard. The filespec argument is the address 
of a descriptor pointing to the file specification. If omitted, this defaults to 
SYS$INPUT. 

default- filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String containing the default file specification. The default-filespec argument 
is the address of a descriptor pointing to the default file specification. If 
omitted, the null string is used. 

Default-filespec might be used to specify a default device and directory, 
leaving the filespec argument to supply the file name and type. 
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resultant- filespec 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

String into which the procedure writes the fully expanded file specification of 
the file used. The resultant-filespec argument is the address of a descriptor 
pointing to the string into which is written the file specification that was used. 

recall-size 

VMS Usage: byte_unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by reference 

Number of input lines to be saved for later recall. The optional recall-size 
argument is the address of an unsigned byte containing the specified number 
of lines. A value of zero turns off input line recall. By default, 20 lines are 
saved for later recall. 


DESCRIPTION SMG$CREATE—VIRTUAL—KEYBOARD creates the association between a 

file specification (terminal name or RMS file) and a virtual keyboard. The 



keyboard identifier is then passed to other SMG$ procedures in order to 
identify the input stream being acted upon. 

If filespec does not refer to a terminal, the file is opened using RMS and all 
further access to that file is performed through RMS. If filespec is a terminal, 
this procedure assigns a channel to the terminal and sets the terminal's 
keyboard to application mode (if supported). These attributes are restored 
to their previous values when the virtual keyboard is deleted. The virtual 
keyboard is deleted automatically when the image exits and can also be 
deleted by a call to SMG$DELETE—VIRTUAL —KEYBOARD. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMGS—FILTOOLON File specification is too long (over 255 characters). 

SMG$_WRONUMARG Wrong number of arguments. 

LIB$_INSEF Insufficient number of event flags. 

LIB$_INSVIRMEM Insufficient virtual memory. 

LIB$_INVSTRDES Invalid string descriptor. 

Any RMS condition values returned by $OPEN or $CONNECT. 

Any condition values returned by $GETDVIW, $ASSIGN, or $DCLEXH. 
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EXAMPLE 


C+ 

C This FORTRAN example program demonstrates the use of 
C SMG$CREATE_VIRTUAL_KEYBOARD. SMG$CREATE_KEY_TABLE, 

C SMG$ADD_KEY_DEF, and SMG$READ_COMPOSED_LINE. 

C- 

INTEGER SMG$CREATE_VIRTUAL_KEYBOARD. SMG$CREATE_KEY_TABLE 
INTEGER SMG$ADD_KEY_DEF, SMG$READ_COMPOSED_LINE 
INTEGER SMG$DELETE_KEY_DEF, KEYBOARD, KEYTABLE, STATUS 

C+ 

C Include the SMG definitions. In particular, we want SMG$MJKEY_NOECHO 
C and SMG$M_KEY_TERMINATE. 

C- 


INCLUDE '($SMGDEF)' 


C+ 

C Create a virtual keyboard (using SMG$CREATE_VIRTUAL_KEYBOARD) 

C and create a key table (using SMG$CREATE_KEY_TABLE). 

C- 

STATUS = SMG$CREATE_VIRTUAL_KEYBOARD (KEYBOARD) 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 

STATUS = SMG$CREATE_KEY_TABLE (KEYTABLE) 

IF (.NOT. STATUS) CALL LIB$SIGNALOiVAL(STATUS)) 

C+ 

C Prompt the user with the following instructions. 

C- 

WRITE (6,*) 

WRITE (6,*) 

WRITE (6,0 
WRITE (6,*) 

WRITE (6.*) 

WRITE (6,*) 

WRITE (6,*) 

WRITE (6,*) 

WRITE (6,0 
WRITE (6,*) 

WRITE (6,0 
WRITE (6,*) 

C+ 

C Add key definitions by calling SMG$ADD_KEY_DEF. 

C- 

STATUS = SMG$ADD_KEY_DEF (KEYTABLE, 'PF1' # . , 

1 ’NOW IS THE TIME FOR ') 

IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 

STATUS = SMG$ADD_KEY_DEF (KEYTABLE, 'KP5', . . 

1 'TEXT TO APPEAR.') 

IF (.NOT. STATUS) CALL LIB$SIGNALOiVAL(STATUS)) 

STATUS = SMG$ADD_KEY_DEF (KEYTABLE. 'PF3', . 

1 SMG$M_KEY_NOECHO + SMG$M_KEY_TERMINATE , 

1 'THIS SHOULD NOT BE ECHOED. IF YOU CAN 
1 SEE THIS, AN ERROR EXISTS.') 

IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 

C+ 

C Call SMG$READ_COMPOSED_LINE to read a line of input. 

C- 

WRITE(6,0 ' ' 

STATUS = SMG$READ_COMPOSED_LINE (KEYBOARD, KEYTABLE, R.TEXT, 
1 '->') 

IF (.NOT. STATUS) CALL LIB$SIGNAL(7.VAL(STATUS)) 

END 


'When you see the prompt (->), strike the following' 
•keys (on the KEYPAD): ' 

' PF1 ' 

' 5 ' 

• PF3 ' 

i i 

'When you have done this, the following sentence' 
'(and nothing more) should appear following the' 

'prompt: ' 

'(PF3 should act as a carriage return.)' 

i i 

■NOW IS THE TIME FOR ALL TEXT TO APPEAR. ' 


Output session: 
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$ RUN example 

When you see the prompt (-> ), strike the following keys (on the KEYPAD): 

• PF1 

• 5 

• PF3 

After entering PF3, the following sentence should appear following the 
prompt: 

NOW IS THE TIME FOR ALL TEXT TO APPEAR. 

->NOW IS THE TIME FOR ALL TEXT TO APPEAR. 

$ 
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SMG$CURSOR_COLUMN 
Return Cursor Column Position 



SMG$CURSOR_COLUMN returns the virtual cursor's current column 
position in a specified virtual display. 

FORMAT 

SMG$CURSOR_COLUMN display-id 

RETURNS 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

SMG$CURSOR_COLUMN returns the current virtual cursor column 
position. 

ARGUMENT 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The display for which the column position is returned. The display-id 
argument is the address of an unsigned longword that contains the display 
identifier. 

Display-id is returned by SMG$CREATE-VIRTUAL-DISPLAY. 

DESCRIPTION 

SMG$CURSOR—COLUMN returns a longword containing the value of the 
current virtual cursor column position for the specified virtual display. If 
the display-id is omitted, this routine signals SMG$_WRONUMARG. If the 
display-id is invalid, this routine signals SMG$_INVDIS—ID. 

CONDITION 

VALUES 

SIGNALED 

SMG$_INVDIS_ID Invalid display-id 

SMG$_WRONUMARG Wrong number of arguments 
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SMG$CURSOR_ROW—Return Cursor Row 

Position 



SMG$CURSOR_ROW returns the virtual cursor's current row 
position in a specified virtual display. 

FORMAT 

SMG$CURSOR_ROW display-id 

RETURNS 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

SMG$CURSOR_ROW returns the current row position. 

ARGUMENT 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The display for which the row position is returned. The display-id argument 
is the address of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE—VIRTUAL —DISPLAY. 

DESCRIPTION 

SMG$CURSOR_ROW returns a longword containing the value of the current 
virtual cursor row position for the specified virtual display. 

CONDITION 

VALUES 

SIGNALED 

SMG$_INVDIS_ID Invalid display-id 

SMG$_WRONUMARG Wrong number of arguments 
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SMG$DEFINE_KEY—Perform a DEFINE 

/KEY Command 



SMG$DEFINE_KEY performs the DEFINE/KEY command you 
provide. 

FORMAT 

SMG$DEFINE_KEY key-table-id,command-line 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

key-table-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Identification of the key definition table for which the DEFINE/KEY 
command is to be performed. The key-table-id argument is the address 
of an unsigned longword that contains the key table identifier. 

Key-table-id is returned by SMG$CREATE _KE Y—TABLE. 

command-line 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String containing the DEFINE/KEY command to be performed. The 
command-line argument is the address of a descriptor pointing to the 
command to be performed. 

The valid qualifiers for the DEFINE/KEY command are: 

• /PROTECT 

• /TERMINATE 


• /NOECHO 

• /LOCK 


DESCRIPTION SMG$DEFINE_KEY parses and performs a DEFINE/KEY command. It can 
be used by programs that accept DEFINE/KEY commands but do not parse 
the commands themselves. 
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SMG$DEFINE_KEY calls CLI$DCL—PARSE to parse the command line 
and then makes the appropriate call to SMG$ADD—KEY—DEF. Use of this 
procedure requires that the image be run under the DCL Command Language 
Interpreter. 


CONDITION 

SSS—NORMAL 

Normal successful completion. 

VALUES 

SMG$_WRONUMARG 

Wrong number of arguments. 

RETURNED 

Any condition values 
Any condition values 

Any condition values 

returned by LIB$SCOPY_DXDX. 
returned by CLI$ routines, 
returned by SMG$ADD_KEY—DEF. 
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SMG$DEI_TERM-TABLE—Delete 

Terminal Table 



SMG$DEL_TERM_TABLE terminates access to TERMTABLE.EXE 
and frees the associated virtual address space. 

FORMAT 

SMG$DEI_TERM-TABLE 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

None. 

DESCRIPTION 

SMG$DEL_TERM_TABLE terminates access to TERMTABLE.EXE. Calling 
this routine is optional. This routine is useful only in the case where a calling 
program might need to reuse the virtual address space used by a private 
TERMTABLE. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 
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SMG$DELETE_CHARS—Delete Characters 

SMG$DELETE_CHARS deletes characters in a virtual display. 

FORMAT 

SMG$DELETE_CHARS display-id ,num-chars ,row 

, column 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Identifies the virtual display from which characters are to be deleted. The 
display-id argument is the address of an unsigned longword integer that 
contains the display identifier. 

Display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY. 


num-chars 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the number of characters to be deleted. The num-chars argument 
is the address of a signed longword integer that contains the number of 
characters to be deleted. 


row 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the row position at which to start the deletion. The row argument 
is the address of a signed longword integer that contains the row number at 
which to start the deletion. 


column 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column position at which to start the deletion. The column 
argument is the address of a signed longword integer that contains the 
column position at which to start the deletion. 
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DESCRIPTION SMG$DELETE_CHARS deletes a specified number of characters, starting 

at a specified row and column position. Remaining characters on the line 
are shifted to the left to occupy the vacated space(s). Note that this routine 
deletes characters only on a single line. 

If you specify more characters than are available for deletion, SMG$DELETE_ 
CHARS deletes all characters from the specified column position to the end 
of the line. 

This routine leaves the virtual cursor at the position of the first character 
deleted. 


CONDITION 

SS$_NORMAL 

Normal successful completion. 

VALUES 

SMG$_INVROW 

Invalid row position. The specified row is outside 

RETURNED 


the virtual display. 


SMG$_INVCOL 

Invalid column position. The specified column is 
outside the virtual display. 


SMG$_INVDIS_ID 

Invalid display-id. 


SMG$_WRONUMARG 

Wrong number of arguments. 


SMG$_INVARG 

Invalid argument. The number of characters 
specified extends outside virtual display. 


EXAMPLE 


O 

C This FORTRAN example program demonstrates the use of 
C SMG$DELETE_CHARS. 

C- 

INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD 
INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$PUT_CHARS, SMG$DELETE_CHARS 
INTEGER DISPLAY1, PASTE1, ROWS, COLUMNS, BORDER 
C+ 

C Create the virtual display be calling SMG$CREATE_VIRTUAL_DISPLAY. 

C To give it a border, set BORDER = 1. No border would be BORDER = 0. 

C- 

ROWS = 7 
COLUMNS = 50 
BORDER = 1 

ISTATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS, COLUMNS, DISPLAY1, BORDER) 

IF (.NOT. ISTATUS) WRITE (6. 900) 'SMG$CREATE_VIRTUAL_DISPLAY', ISTATUS 
C+ 

C Call SMG$CREATE_PASTEBOARD to create the pasteboard. 

C- 

ISTATUS = SMG$CREATE_PASTEBOARD (PASTED 

IF (.NOT. ISTATUS) WRITE (6, 900) 'SMG$CREATE_PASTEBOARD•, ISTATUS 
C+ 

C Use SMG$PUT_CHARS to put data in the virtual display. 

C- 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This virtual display has 7 rows and 50 columns.', 2, 1) 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This is a bordered virtual display.', 4, 1) 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' SMG$PUT_CHARS puts data in this virtual display.', 6, 1) 

C+ 

C Paste the virtual display to the pasteboard using 
C SMG$PASTE_VIRTUAL_DISPLAY. 

C- 
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ISTATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15) 
900 FORMAT (' Routine ', A, ' returned a status of Z8) 

Call SMG$DELETE_CHARS to delete 4 characters from row 4 
C starting from character (column) 14, removing the characters 
C "rder" from the word "bordered". 

C- 

ISTATUS = SMG$DELETE_CHARS ( DISPLAY1, 4, 4, 14) 

END 


The output generated by this FORTRAN program before the call to 
SMG$DELETE_CHARS is shown in Figure RTL-11. 

Figure RTL-11 Output Generated Before the Call to 

SMG$DELETE_CHARS 
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The output generated after the call to SMG$DELETE_CHARS is shown in 
Figure RTL-12. 
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Figure RTL-12 


Output Generated After the Call to 
SMG$DELETE_CHARS 
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SMG$DELETE_KEY_DEF—Delete Key 

Definition 

SMG$DELETE_KEY_DEF deletes a key definition from a specified 
table of key definitions. 


FORMAT 

SMG$DELETE_KEY_DEF 

key-table-id ,key-name 
[, if-state] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 

key-table-id 



VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 



Identifies the key table from which the key definition is deleted. The key- 
table-id argument is the address of an unsigned longword that contains the 
key table identifier. 


key-name 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String containing the name of the key whose definition is to be deleted. The 
key-name argument is the address of a descriptor pointing to the key name. 
Key-name is stripped of trailing blanks and converted to uppercase before 
use. 

Table 3-1 in Part I of this manual lists the valid key names. 


if-state 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String containing a state name which further qualifies key-name. The if-state 
argument is the address of a descriptor pointing to the state name. If omitted, 
the null state is used. Thus if a key has several definitions depending on 
various values of if-state, this routine lets you delete only one of those 
definitions. 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


SMG$DELETE_KEY_DEF deletes a key definition from a specified table of 
key definitions. 


SS$_NORMAL 

SMG$_INVKTB_ID 

SMG$_KEYNOTDEF 

SMG$_WRONUMARG 

SMG$_KEYDEFPRO 


Normal successful completion. 
Invalid key-table-id. 

Key is not defined. 

Wrong number of arguments. 
Key definition is protected. 
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SMG$DELETE_LINE—Delete Line 



SMG$DELETE_LINE deletes lines from a virtual display. 

FORMAT 

SMG$DELETE_LINE display-id,start-line 

[,number-lines] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Identifies the virtual display from which lines are to be deleted. The display- 
id argument is the address of an unsigned longword that contains the display 
identifier. 

Display-id is returned by SMG$CREATE_VIRTUAl^DISPLAY. 

start-line 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the first line to be deleted from the virtual display. The start-line 
argument is the address of a signed longword integer that contains the 
number of the first line to be deleted. 

number-lines 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the number of lines to be deleted. The number-lines argument is 
the address of a signed longword integer that contains the number of lines to 
be deleted. If omitted, one line is deleted. 

DESCRIPTION 

SMG$DELETE_LINE deletes one or more lines from a virtual display and 
scrolls the remaining lines up into the space created by the deletion. Blank 
lines fill the display on the bottom. The virtual cursor is left at the first 
column position in start-line. 


RTL-583 











Run-Time Library Routines 

SMG$DELETE_LINE 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_INVDIS_ID 

SMG$_WRONUMARG 

SMG$_INVROW 

SMG$_INVARG 


Normal successful completion. 
Invalid display-id. 

Wrong number of arguments. 
Invalid row. 

Invalid argument. 


EXAMPLE 


C+ 

c This FORTRAN example program demonstrates the use of SMG$DELETE_LINE. 

C- 

INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD 
INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$PUT_CHARS, SMGDELETE.LINE 
INTEGER DISPLAY1, PASTE1, ROWS, COLUMNS. BORDER 
C+ 

c Create the virtual display by calling SMG$CREATE_VIRTUAL_DISPLAY. 

C To give it a border, set BORDER ■ 1. No border would be BORDER = 0. 

C- 

ROWS = 7 
COLUMNS = 50 
BORDER = 1 

ISTATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS, COLUMNS, DISPLAY1, BORDER) 

IF (.NOT. ISTATUS) WRITE (6, 900) 'SMG$CREATE_VIRTUAL_DISPLAY', ISTATUS 
C+ 

C Call SMG$CREATE_PASTEBOARD to create the pasteboard. 

C- 

ISTATUS = SMG$CREATE_PASTEBOARD (PASTED 

IF (.NOT. ISTATUS) WRITE (6, 900) 'SMG$CREATE_PASTEBOARD', ISTATUS 
C+ 

C Use SMG$PUT_CHARS to put data in the virtual display. 

C- 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This virtual display has 7 rows and 50 columns.', 2, 1) 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This is a bordered virtual display.', 4, 1) 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' SMG$PUT_CHARS puts data in this virtual display.', 6, 1) 

C+ 

C Paste the virtual display to the pasteboard using 
C SMG$PASTE_VIRTUAL_DISPLAY. 

C- 

ISTATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1. 4, 15) 

900 FORMAT (' Routine ', A, ' returned a status of ', Z8) 

C+ 

C Call SMG$DELETE_LINE to delete rows 3, 4, and 5. 

C- 

ISTATUS = SMG$DELETE_LINE ( DISPLAY1, 3. 3) 

END 


The output generated by this FORTRAN program before the call to 
SMG$DELETE_LINE is shown in Figure RTL-13. 
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Figure RTL-13 


Output Generated by FORTRAN Program Before 
the Call to SMG$DELETE_LINE 



The output generated after the call to SMG$DELETE_LINE is shown in 
Figure RTL-14. 

Figure RTL-14 Output Generated After the Call to 
SMG$DELETE_LINE 
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SMG$DELETE—PASTEBOARD—Delete 

Pasteboard 



SMG$DELETE_PASTEBOARD deletes a pasteboard. 

FORMAT 

SMG$DELETE_PASTEBOARD pasteboard-id 

[, clear-screen-flag] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard to be deleted. The pasteboard-id argument is the 
address of an unsigned longword that contains the pasteboard identifier. 

Pasteboard-id is returned by SMG$CREATE—PASTEBOARD. 

clear-screen-flag 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Determines whether this routine clears the screen after deleting the specified 
pasteboard. The clear-screen-flag argument is the address of an unsigned 
longword that contains the flag. If clear-screen-flag is 1, the screen is cleared; 
if 0, the screen is not cleared. If this argument is omitted, the default is to 
clear the screen. 

DESCRIPTION 

SMG$DELETE_PASTEBOARD flushes all output to the display, terminates 
all use of the specified pasteboard, and deallocates all resources associated 
with the pasteboard. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_WRONUMARG Wrong number of arguments. 

SMG$_INVPAS_ID Invalid pasteboard-id. 

SMG$_NOTPASTED The specified virtual display is not pasted to the 

specified pasteboard. 

Any condition values returned by $DASSGN, LIB$FREE_VM, LIB$FREE_EF, 
or SMG$FLUSH_BUFFER. 
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SMG$DELETE_VIRTUAL-DISPLAY 
Delete Virtual Display 



SMG$DELETE_VIRTUAI_DISPLAY deletes a virtual display. 

FORMAT 

SMG$DELETE_VIRTUAI_DISPLAY display-id 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display to be deleted. The display-id argument is the 
address of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE-VIRTUAL-DISPLAY. 

DESCRIPTION 

SMG$DELETE_VIRTUAL—DISPLAY deletes a virtual display and removes 
it from any pasteboard on which it is pasted. It also deallocates any buffer 
space associated with the virtual display. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_INVDIS_ID Invalid display-id. 

SMG$_WRONUMARG Wrong number of arguments. 

SMG$_NOTPASTED The specified virtual display is not pasted to the 

specified pasteboard. 

Any condition values returned by LIB$FREE_VM. 
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SMG$DELETE -VIRTUAL -KEYBOARD 
Delete Virtual Keyboard 



SMG$DELETE_VIRTUAL-KEYBOARD deletes a virtual keyboard. 

FORMAT 

SMG$DELETE_VIRTUAI_KEYBOARD 

keyboard-id 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

keyboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual keyboard to be deleted. The keyboard-id argument is 
the address of an unsigned longword that contains the keyboard identifier. 

Keyboard-id is returned by SMG$CREATE-VIRTUAL -KEYBOARD. 

DESCRIPTION 

SMG$DELETE_VIRTUAL-KEYBOARD deletes a virtual keyboard. Any 
terminal attributes specified when the keyboard was created are reset to their 
previous values and the keypad mode (numeric or application) is reset to 
its original state. In addition, the channel is deassigned and, if the virtual 
keyboard was a file, the file is closed. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_NOT_A_TRM Informational message. The device was not a 

terminal. 

SMG$_INVKBD_ID Invalid keyboard-id. 

SMG$_WRONUMARG Wrong number of arguments. 
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SMG$DISABLE_BROADCAST—TRAPPING 
Disable Broadcast Trapping 



SMG$DISABLE-BROADCAST-TRAPPING disables trapping of 
broadcast messages for the specified terminal. 

FORMAT 

SMG$DISABLE_BROADCAST_TRAPPING 

pasteboard-id 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

pasteboard-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard for the terminal to be affected. The pasteboard-id 
argument is the address of an unsigned longword that contains the pasteboard 
identifier. 

DESCRIPTION 

SMG$DISABLE_BROADCAST_TRAPPING disables trapping of broadcast 
messages for the specified terminal. SMG$DISABLE—BROADCAST— 
TRAPPING deassigns the mailbox set with SMG$SET_BROADCAST— 
TRAPPING, resets the terminal characteristics, and therefore allows the user 
to SPAWN a subprocess. This routine must be used to disable any broadcast 
trapping set with the routine SMG$SET_BROADCAST_TRAPPING. 

Note that if both broadcast trapping and the trapping of unsolicited input 
are enabled, then both SMG$DIS ABLE-BROADCAST-TRAPPING and 
SMG$DIS ABLE-UNSOLICITED-INPUT must be invoked to deassign the 
mailbox. 

CONDITION 

VALUES 

RETURNED 

SSS—NORMAL Normal successful completion 

SMGS—WRONUMARG Wrong number of arguments 

Any condition value returned by $QIOW. 
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EXAMPLE 


10 


! + 

IThis program creates three virtual displays on one pasteboard. 
!The first virtual display contains instructions for the user, 
!the second shows trapped unsolicited input, and the third 
!list8 trapped broadcast messages. The program sits in an 
{infinite loop until the user types a CTRL/Z. 

IWhen the program traps unsolicited input, both broadcast message 
land unsolicited input trapping are disabled, and a subprocess 
lis spawned which executes the trapped user input. 


IWhen control returns to the main process, broadcast trapping and 
Ithe trapping of unsolicited input are both reenabled. If the 
!unsolicited input which is trapped is a CTRL/Z, the program exits. 
! - 

OPTION TYPE = EXPLICIT 
! ♦ 



!Declaration of all routines called by the main program. 

i - 


EXTERNAL 

EXTERNAL 

EXTERNAL 


SUB LIB$ST0P 
LONG FUNCTION 
LONG FUNCTION 


EXTERNAL LONG FUNCTION 


EXTERNAL LONG FUNCTION 


EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 


(LONG BY VALUE) 

SMG$CREATE_PASTEBOARD (LONG) 
SMG$CREATE_VIRTUAL_DISPLAY (LONG, LONG, & 
LONG, LONG. LONG) 

SMG$PASTE_VIRTUAL_DISPLAY (LONG, LONG, & 
LONG, LONG) 

SMG$PUT_LINE (LONG, STRING, LONG. LONG, & 
LONG, LONG) 

SMG$SET_BROADCAST_TRAPPING (LONG, LONG) 
SMG$CREATE_KEY_TABLE (LONG) 
SMG$CREATE_VIRTUAL_KEYBOARD (LONG) 
SMG$LABEL_BORDER (LONG, STRING. LONG, & 
LONG, LONG, LONG) 

SMG$ENABLE_UNSOLICITED_INPUT (LONG, LONG, 
LONG) 

LONG FUNCTION SMG$DISABLE_UNSOLICITED_INPUT (LONG) 

LONG FUNCTION SMG$DISABLE_BR0ADCAST_TRAPPING (LONG) 

LONG FUNCTION SMG$DELETE_PASTEBOARD (LONG) 


LONG FUNCTION 
LONG FUNCTION 
LONG FUNCTION 
LONG FUNCTION 



EXTERNAL LONG FUNCTION 

EXTERNAL 
EXTERNAL 
EXTERNAL 

| + 

!Declaration of the two AST routines: 

IGET.MSG is called when a broadcast message is trapped 
!GET_INPUT is called when there is unsolicited input - 
!GET_INPUT is the routine which spawns the subprocess 

i - 



EXTERNAL INTEGER GET.MSG 

EXTERNAL INTEGER GET.INPUT 

DECLARE LONG pb_id, ret_status, display.id, display2_id, display3_id, & 
key_id, key_tab_id, counter 

! + 

!Create a MAP area for variables which must be shared between the 
Imain program and the AST routines. 




MAP (params) LONG disp.info(2), LONG keyboard_info(4), LONG done.flag 


DECLARE STRING CONSTANT top.label 
DECLARE STRING CONSTANT ins.label 
DECLARE STRING CONSTANT msg.label 
DECLARE STRING CONSTANT instr.O = 
DECLARE STRING CONSTANT instr.l = 
DECLARE STRING CONSTANT instr_2 = 
DECLARE LONG CONSTANT advance = 
DECLARE LONG CONSTANT wrap = 1 


= "User Input" 

= "Instructions" 

= "Messages" 

"Type commands to fill INPUT display." 
"Type CTRL/T to fill MESSAGES display." 
"Type CTRL/Z to exit." 


! + 


!Declare any external constants used in the program. The values 
Ifor these constants are assigned when you link the program with 
!SMGDEF. 
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I - 

EXTERNAL LONG CONSTANT SMG$M_B0LD 
EXTERNAL LONG CONSTANT SMG$M_REVERSE 
EXTERNAL LONG CONSTANT SMG$M_BLINK 
EXTERNAL LONG CONSTANT SMG$M_UNDERLINE 

EXTERNAL LONG CONSTANT SMG$M_BORDER 
EXTERNAL LONG CONSTANT SMG$_E0F 
EXTERNAL LONG CONSTANT SS$_NORMAL 
EXTERNAL LONG CONSTANT SMG$_NO_MORMSG 
• + 

!The done.flag variable is clear (0) unless the user input was 
!a CTRL/Z - in that case the program exits. 

I - 

done_flag = 0 
! + 

•Create the pasteboard and the virtual keyboard 
; - 

ret.status = SMG$CREATE_PASTEBOARD (pb_id) 

IF (ret.status AND 17.) = 0*/. THEN 

CALL LIB$STOP(ret_status BY VALUE) 

END IF 

! + 

!This is one of the values which must be stored in the MAP area. 
; - 

di8p_info(0) = pb_id 

ret.status = SMG$CREATE_VIRTUAL_KEYBOARD (key.id) 

IF (ret.status AND 1%) * 0% THEN 

CALL LIBISTOP(ret.status BY VALUE) 

END IF 

ret.status = SMGlCREATE.KEY.TABLE (key.tab.id) 

IF (ret.status AND 17.) = 07. THEN 

CALL LIB$STOP(ret.status BY VALUE) 

END IF 

! + 

!Create the three virtual displays 
; - 

ret.status = SMG$CREATE_VIRTUAL.DISPLAY(3 BY REF, 75 BY REF, & 
display3_id, SMG$M_BORDER BY REF, SMG$M_REVERSE BY REF) 
IF (ret.status AND 17.) = 07. THEN 

CALL LIB$STOP(ret.status BY VALUE) 

END IF 

ret.status = SMGlCREATE.VIRTUAL.DISPLAY(6 BY REF, 75 BY REF, & 
display.id, SMGlM.BORDER BY REF, SMG$M_REVERSE BY REF) 

IF (ret.status AND 17.) = 07. THEN 

CALL LIBISTOP(ret.status BY VALUE) 

END IF 

ret.status * SMGlCREATE.VIRTUAL.DISPLAY(6 BY REF. 75 BY REF, & 
display2_id, SMGlM.BORDER BY REF, SMGlM.REVERSE BY REF) 
IF (ret.status AND 17.) = 07. THEN 

CALL LIBISTOP(ret.status BY VALUE) 

END IF 

! + 

!The disp.info and keyboard.info arrays are required in the MAP. 

i - 

disp.info(1) = display2_id 

keyboard.info(0) = key.id 
keyboard.info(l) = key.tab.id 
keyboard.info(2) = display.id 
keyboard.info(4) = pb.id 
! + 

!Put Label borders around the three virtual displays. 

ret.status = SMGlLABEL.BORDER (display3_id, ins.label,,, & 
SMGIM.BOLD BY REF, SMGlM.REVERSE BY REF) 

IF (ret.status AND 17.) = 07. THEN 
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CALL LIB$STOP(ret_status BY VALUE) 

END IF 

ret.status = SMG$LABEL_BORDER (display.id, top.label,,, & 
SMG$M_BOLD BY REF,) 

IF (ret.status AND 1%) = 07. THEN 

CALL LIB$ST0P(ret_8tatus BY VALUE) 

END IF 

ret.status * SMG$LABEL_BORDER (display2_id, msg.label,,, & 
SMG$M_B0LD BY REF,) 

IF (ret.status AND 17.) = 0% THEN 

CALL LIBISTOP(ret.status BY VALUE) 

END IF 


!Fill the INSTRUCTIONS virtual display with user instructions. 

ret.status * SMG$PUT_LINE(display3_id, instr.O, advance,,, wrap) 
IF (ret.status AND 17.) = 07. THEN 

CALL LIB$STOP(ret.status BY VALUE) 

END IF 

ret.status * SMG$PUT_LINE(display3_id, instr.l, advance,,, wrap) 
IF (ret.status AND 17.) * 07. THEN 

CALL LIB$ST0P(ret.status BY VALUE) 

END IF 

ret.status = SMG$PUT_LINE(display3_id, instr.2, advance,,, wrap) 
IF (ret.status AND 17.) = 07. THEN 

CALL LIBlSTOP(ret.status BY VALUE) 

END IF 

! + 

!Paste the virtual displays to the screen. 


ret.status * SMG$PASTE_VIRTUAL_DISPLAY(display3_id, pb.id, & 

2 BY REF. 4 BY REF) 

IF (ret.status AND 17.) = 07. THEN 

CALL LIBISTOP(ret.status BY VALUE) 

END IF 

ret.status = SMG$PASTE_VIRTUAL_DISPLAY(display.id, pb.id, & 

8 BY REF, 4 BY REF) 

IF (ret.status AND 17.) = 07. THEN 

CALL LIB$STOP(ret.status BY VALUE) 

END IF 

ret.status = SMG$PASTE_VIRTUAL_DISPLAY(display2_id, pb.id, & 

18 BY REF. 4 BY REF) 

IF (ret.status AND 17.) = 07. THEN 

CALL LIBISTOP(ret.status BY VALUE) 

END IF 
• + 

!Enable the trapping of unsolicited input. GET.INPUT is the 
!AST procedure that is called when unsolicited input is 
!received. This AST has one parameter, passed as null. 

j - 

ret.status = SMG$ENABLE_UNSOLICITED_INPUT(pb.id, GET.INPUT,) 

IF (ret.status AND 17.) = 07. THEN 

CALL LIBlSTOP(ret.status BY VALUE) 

END IF 

• + 

'.Enable the trapping of broadcast messages. GET.MSG is the 
!AST which is called when broadcast messages are received. 

!This AST outputs the trapped message into the MESSAGES display. 

j - 

ret.status = SMG$SET_BROADCAST_TRAPPING(pb.id, GET.MSG) 

IF (ret.status AND 17.) = 07. THEN 

CALL LIBISTOP(ret.status BY VALUE) 

END IF 

! + 

'.This loop continually executes until done.flag is set to 1. 
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!Done_flag is set to 1 when the user input is a CTRL/Z. 

!If done_flag is 1, delete the pasteboard and exit the program. 

j - 

Infinite_loop: 

IF done.flag = 0 THEN 
GOTO infinite.loop 
ELSE 

ret.status = SMG|DELETE_PASTEBOARD (pb_id) 

GOTO all.done 
END IF 

All_done: 

END 


20 


!Start of AST routine GET_INPUT. This AST is called whenever there 
!is unsolicited input. The unsolicited input is displayed in the 
!INPUT virtual display, and if this input is not CTRL/Z, a subprocess 
!is spawned and the input command is executed. While this spawned 
Isubprocess is executing, broadcast and unsolicited input trapping 
!is disabled, 
i - 

SUB GET_INPUT (paste.id, param, null.l, null_2, null_3, null_4) 

MAP (params) LONG disp.info(2), LONG keyboard.info(4), LONG done.flag 

DECLARE LONG z.status, status2, keybd_id, keybd_tab_id, disp_id, & 
pastebd, new_display 
DECLARE WORD msg2_len 
DECLARE STRING msg2 
DECLARE LONG CONSTANT next.line = 1 
DECLARE LONG CONSTANT wrap.flag = 1 


EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 


LONG FUNCTION SMG$READ_COMPOSED_LINE (LONG. LONG, STRING, k 
STRING, WORD. LONG) 

LONG FUNCTION SMG$SET_BROADCAST_TRAPPING (LONG. LONG) 

LONG FUNCTION SMG$ENABLE_UNSOLICITED_INPUT (LONG, LONG, & 
LONG) 

LONG FUNCTION SMG$DISABLE_UNSOLICITED_INPUT (LONG) 

LONG FUNCTION SMG$DISABLE_BROADCAST_TRAPPING (LONG) 

LONG FUNCTION SMG$SAVE_PHYSICAL_SCREEN (LONG, LONG) 

LONG FUNCTION SMG$RESTORE_PHYSICAL_SCREEN (LONG, LONG) 

SUB LIBISPAWN (STRING) 

SUB LIBlSTOP (LONG BY VALUE) 

INTEGER GET.MSG 

INTEGER GET_INPUT 


EXTERNAL LONG CONSTANT SMG$_EOF 
EXTERNAL LONG CONSTANT SS$_NORMAL 


! + 

!Assign to the local variables the values that were stored from 
!the main program using the MAP area. 

i - 


keybd.id = keyboard.info(0) 
keybd_tab_id = keyboard_info(l) 
disp_id * keyboard_info(2) 
pastebd = keyboard__inf o(3) 

! + 

!SMG$ENABLE_UNSOLICITED_INPUT does not read the input, it simply 
!signals the specified AST when there is unsolicited input present. 
!You must use SMG$READ_COMPOSED_LINE to actually read the input. 


!At this time, we check to see if the unsolicited input was a CTRL/Z. 
!If so, we skip over the program lines that spawn the subprocess and 
!get ready to exit the program. 

i - 

status2 = SMG$READ_COMPOSED_LINE (keybd.id, keybd.tab.id, msg2,. h 
msg2_len, disp.id) 

IF (status2 = SMGI.EOF) THEN 
GOTO Control.Z 
END IF 

IF (status2 AND 1%) = 07. THEN 

CALL LIB$ST0P (status2 BY VALUE) 
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END IF 


!In order to spawn a subprocess, we must first disable 
!unsolicited input trapping and broadcast trapping, 
i - 

status2 = SMG|DISABLE_UNSOLICITED_INPUT (pastebd) 

IF (status2 AND 1%) = 0% THEN 

CALL LIBISTOP (status2 BY VALUE) 

END IF 

status2 = SMG$DISABLE_BR0ADCAST.TRAPPING (pastebd) 

IF (status2 AND 17.) = 07, THEN 

CALL LIBISTOP (status2 BY VALUE) 

END IF 
! + 

!Save the current screen so that it will not be destroyed when 
!the subprocess is executing. 

; - 

status2 = SMG|SAVE_PHYSICAL_SCREEN (pastebd, new.display) 

IF (status2 AND 17.) * 07. THEN 

CALL LIBISTOP (status2 BY VALUE) 

END IF 
! ♦ 

!Call LIBlSPAWN to create the subprocess, and pass the unsolicited 
!input as the command line. 

j - 

CALL LIBlSPAWN (msg2) 

! + 

!Restore the saved screen image. 

i - 

status2 = SMG|RESTORE_PHYSICAL_SCREEN (pastebd, new.display) 

IF (status2 AND 17.) * 07. THEN 

CALL LIBISTOP (status2 BY VALUE) 

END IF 
!♦ 

'Reenable broadcast trapping and unsolicited input trapping. 

! - 

status2 = SMG|SET_BROADCAST_TRAPPING (pastebd, GET.MSG) 

IF (status2 AND 17.) = 07. THEN 

CALL LIBISTOP (status2 BY VALUE) 

END IF 

status2 = SMG|ENABLE_UNSOLICITED_INPUT (pastebd, GET_INPUT,) 

IF (status2 AND 17.) = 07. THEN 

CALL LIBISTOP (status2 BY VALUE) 

END IF 
! + 

!Skip the steps which are preformed if the unsolicited input 
!was a CTRL/Z. 

i - 

GOTO Out_of_sub 
Control_Z: 

! + 

!We have to disable unsolicited input and broadcast trapping 
!before we can leave the program. 

status2 = SMGIDISABLE.UNSOLICITED.INPUT (pastebd) 

IF (status2 AND 17.) = 07. THEN 

CALL LIBISTOP (status2 BY VALUE) 

END IF 

status2 = SMGIDISABLE_BR0ADCAST_TRAPPING (pastebd) 

IF (status2 AND 17.) * 07. THEN 

CALL LIBISTOP (status2 BY VALUE) 

END IF 
!♦ 

!Set the done_flag to 1 so that the main program knows we have 
!to exit. 
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done.flag = 1 

Out_of_sub: 

END SUB 

30 ! ♦ 

!Start of AST routine GET.MSG. This AST is called whenever there 
!is a broadcast message. This routine prints the message in the 
!MESSAGES virtual display. 

i - 

SUB GET.MSG (paste.id, nl.l, nl.2, nl_3, nl_4) 

DECLARE LONG statusl, pasteboard, second.disp 

DECLARE WORD msg.len 

DECLARE STRING msg 

DECLARE LONG CONSTANT forward = 1 

DECLARE LONG CONSTANT wrp.flag = 1 

MAP (params) LONG disp_info(2), LONG keyboard.info(4) 

EXTERNAL LONG FUNCTION SMG$PUT_LINE (LONG, STRING. LONG, LONG. & 

LONG, LONG) 

EXTERNAL LONG FUNCTION SMG$GET_BROADCAST_MESSAGE (LONG, STRING, & 

WORD) 

EXTERNAL SUB LIB$STOP (LONG BY VALUE) 

EXTERNAL LONG CONSTANT SMG$_NO_MORMSG 
! + 

!Assign values to the local variables according to the values stored 
!in the MAP area. 


pasteboard = disp_info(0) 

8econd_disp * disp_info(l) 
t + 

!Print the trapped message in the MESSAGES display. If there are no 
Imore messages, go back to the infinite loop in the main program, 
j - 

WHILE 1 

statusl = SMG$GET_BROADCAST_MESSAGE (pasteboard, msg, msg.len) 
IF (statusl = SMG$_N0_M0RMSG) THEN 
GOTO Exitloop 
END IF 

IF (statusl AND 1*/.) = 0*/. THEN 

CALL LIB$ST0P (statusl BY VALUE) 

END IF 

statusl = SMG$PUT_LINE (second.disp, msg, forward,,, wrp.flag) 
IF (statusl AND 17.) = 07. THEN 

CALL LIB$ST0P (statusl BY VALUE) 

END IF 

NEXT 

Exitloop: 

END SUB 


Note that this program must be linked with the file SMGDEF.MAR. You build 
this file using the following commands. 

$ CREATE SMGDEF.MAR 

.TITLE SMGDEF - Define SMG$ constants 
.Ident /1-000/ 

$SMGDEF GLOBAL 
.END 

$ MACRO SMGDEF 

To run the example program, use the following commands. 

$ BASIC TRAPPING 
$ LINK TRAPPING,SMGDEF 
$ RUN TRAPPING 

The output for this program is illustrated in the following figures. In 
Figure RTL-14.1, the program is waiting for either unsolicited input or 
broadcast messages. 
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Figure RTL-14.1 Output Generated Before Any Input or 
Messages Are Trapped 



ZK4805-85 


The output generated after the user types a CTRL/T is shown in Figure 
RTL-14.2. 

Figure RTL-14.2 Output Generated After a Broadcast Message 
Is Trapped 
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If the user types a command, that command is displayed in the INPUT 
display, and a subprocess is spawned. The output generated after the user 
types the command MAIL is shown in Figure RTL-14.3. 

Figure RTL-14.3 Output Generated After a Call to LIB$SPAWN 
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Once the subprocess completes execution, control is returned to the main 
process. At this point, the screen is repainted and the program continues 
to wait for broadcast messages or unsolicited input. The user must type a 
CTRL/Z to exit the program. 
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SMG$DISABLE_UNSOLICITED_INPUT 
Disable Unsolicited Input 



SMG$DISABLE_UNSOLICITED_INPUT disables the invocation of 
AST routines for unsolicited input. 

FORMAT 

SMG$DISABLE_UNSOLICITED_INPUT 

pasteboard-id 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the keyboard (associated with the specified pasteboard) for which 
unsolicited input is being disabled. The pasteboard-id argument is the 
address of an unsigned longword that contains the pasteboard identifier. 
Pasteboard-id is returned by SMG$CREATE—PASTEBOARD. 


DESCRIPTION SMG$DISABLE_UNSOLICITED_INPUT disables unsolicited input ASTs 

for the specified pasteboard. SMG$DISABLE_UNSOLICITED_INPUT 



deassigns the mailbox set with SMG$ENABLE_UNSOLICITED—INPUT, 
resets the terminal characteristics, and therefore allows the user to SPAWN 
a subprocess. This routine must be used to disable any unsolicited input 
trapping enabled with the SMG$ENABLE_UNSOLICITED—INPUT routine. 

Note that if both unsolicited input trapping and the trapping of broadcast 
messages are enabled, then both SMG$DIS ABLE-UNSOLICITED-INPUT 
and SMG$DISABLE—BROADCAST—TRAPPING must be invoked in order to 
deassign the mailbox. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_WRONUMARG Wrong number of arguments. 

SMG$_INVPAS_ID Invalid pasteboard-id. 

Any condition values returned by $QIOW. 
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SMG$DISABLE_UNSOLICITED_INPUT 


EXAMPLE 


For an example of using SMG$DISABLE_UNSOLICITED_INPUT, see the 
example for the routine SMG$DIS ABLE-BROADCAST-TRAPPING. 
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SMG$DRAW_LINE 


S MG$DRAW_LI N E—Draw A Line 

SMG$DRAW_LINE draws a horizontal or vertical line. 


FORMAT SMG$DRAW_LINE display-id , start-row 

,start-column,end-row 
,end-column [,rendition-set] 
[,rendition-complement] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


ARGUMENTS display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display on which the line is to be drawn. The display-id 
argument is the address of an unsigned longword that contains the display 
identifier. Display-id is returned by SMG$CREATE—VIRTUAL—DISPLAY. 

start-row 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the row at which to begin drawing the line. The start-row argument 
is the address of a signed longword integer that contains the row number at 
which to begin drawing the line. 

start-column 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column at which to begin drawing the line. The start-column 
argument is the address of a signed longword integer that contains the 
column number at which to begin drawing the line. 
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end-row 


VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the row at which the drawn line ends. The end-row argument is 
the address of a signed longword integer that contains the row number at 
which the drawn line ends. 


end-column 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column at which the drawn line ends. The end-column 
argument is the address of a signed longword integer that contains the 
column number at which the drawn line ends. 


rendition-set 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


A mask which denotes video attributes for the drawn line. The rendition- 
set argument is the address of an unsigned longword that contains a video 
attributes mask. Each bit attribute in this argument causes the corresponding 
attribute to be set in the display. 


Video attributes which can be manipulated in this manner are as follows: 


SMG$M_BLINK 
SMG$M_BOLD 
SMG$M—REVERSE 

SMG$M_UNDERLINE 


Displays blinking characters 

Displays characters in higher-than-normal intensity 

Displays characters in reverse video, that is, using 
the opposite default rendition of the virtual display 

Displays underlined characters 


If the same bit is set in both the rendition-set and rendition-complement 
arguments, the Screen Management Facility applies the rendition-set attribute 
followed by the rendition-complement attribute. Using these two arguments, 
the caller can exercise independent control over each attribute in a single call. 


rendition-complement 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


A mask which denotes video attributes for the line drawn. The rendition- 
complement argument is the address of an unsigned longword that contains 
a video attributes mask. Each bit attribute in this argument causes the 
corresponding attribute to be set in the display. Video attributes which can 
be manipulated in this manner are the same as those for the rendition-set 


argument. 
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SMG$DRAW_LINE 


The following table shows the action taken by the Screen Management 
Facility for various combinations of rendition-set and rendition-complement 
attributes: 


Set 

Complement 

Action 

0 

0 

Attribute unchanged 

1 

0 

Attribute on 

0 

1 

Attribute set to complement of default setting 

1 

1 

Attribute off 


DESCRIPTION 

SMG$DRAW_LINE draws a line from a specified starting row and column to 
a specified ending row and column. You can draw only horizontal or vertical 
lines. The characters used to draw the line depend on the type of terminal. 
The virtual cursor position does not change. 

CONDITION 

SS$_NORMAL 

Normal successful completion. 

VALUES 

SMG$_INVCOL 

Invalid column number. The specified column is 

RETURNED 

SMG$_INVROW 

outside the virtual display. 


Invalid row number. The specified row is outside 
the virtual display 


SMG$_DIALINNOT 

Diagonal line not allowed. 


SMG$_WRONUMARG 

Wrong number of arguments. 


SMG$_INVDIS_ID 

Invalid display-id. 


EXAMPLE 


C+ 

C This FORTRAN example program demonstrates the use of SMG$DRAW_LINE. 
C- 


INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD 
INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$DRAW_LINE 
INTEGER DISPLAY1, PASTE1, ROWS, COLUMNS, BORDER, STATUS 
C+ 

C First, create the virtual display using SMG$CREATE_VIRTUAL_DISPLAY. 

C To give it a border, set BORDER = 1. No border would be BORDER = 0. 

C- 

ROWS = 7 
COLUMNS = 50 
BORDER = 1 

STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS, COLUMNS, DISPLAY1, BORDER) 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 

C+ 

C Call SMG$CREATE_PASTEBOARD to create the pasteboard. 

C- 

STATUS = SMG$CREATE_PASTEBOARD (PASTE1) 

IF (.NOT. STATUS) CALL LIB$SIGNAL C/.VAL (STATUS) ) 

C+ 

C Draw a verticle line using SMG$DRAW_LINE. 

C Start at row 2, column 20. End at row 6. 

C- 


STATUS = SMGSDRAW.LINE (DISPLAY1, 2. 20, 6, 20) 
IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 
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C+ 


C Now, use SMG$DRAW_LINE to draw a verticle line. 

C Start at row 6, column 40. End at row 2. 

C This is similar to the line drawn above, but we are drawing the 
C line in the reverse direction. 

C- 


STATUS = SMG$DRAW_LINE (DISPLAY1, 6, 40, 2, 40) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 

Draw a horizontal line now, again calling SMG$DRAW_LINE. 
Start at row 4, column 8. End at column 50. 


STATUS = SMG$DRAW_LINE (DISPLAY1, 4, 8, 4, 50) 
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 



C+ 

C Paste 
C- 


the virtual display using SMG$PASTE_VIRTUAL_DISPLAY. 


STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4. 15) 
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 


END 


The output generated by this FORTRAN example is shown in Figure RTL-15. 

Figure RTL-15 Output Generated by FORTRAN Program Calling 
SMG$DRAW_LINE 
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SMG$DRAW_RECTANGLE 


SMG$DRAW_RECTANGLE—Draw a 

Rectangle 



SMG$DRAW_RECTANGLE draws a rectangle. 

FORMAT 

SMG$DRAW_RECTANGLE 

display-id, top-left-row 
, top-left-column,bottom-right-row 
, bottom-right-column [, rendition-set] 

[, rendition-complement] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display on which the rectangle is to be drawn. The 
display-id argument is the address of an unsigned longword that contains 
the display identifier. 

Display-id is returned by SMG$CREATE-VIRTUAL-DISPLAY. 

top-left-row 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the row number of the top left-hand comer of the rectangle. The 
top-left-row argument is the address of a signed longword integer that 
contains the row number of the top left-hand comer of the rectangle. 

top-left-column 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column number of the top left-hand comer of the rectangle. The 
top-left-column argument is the address of a signed longword integer that 
contains the column number of the top left-hand comer of the rectangle. 
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bottom-right-row 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the row number of the bottom right-hand comer of the rectangle. 
The bottom-right-row argument is the address of a signed longword 
integer that contains the row number of the bottom right-hand comer of 
the rectangle. 


bottom-right-column 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column number of the bottom right-hand corner of the rectangle. 
The bottom-right-column argument is the address of a signed longword 
integer that contains the column number of the bottom right-hand corner of 
the rectangle. 


rendition-set 


VMS Usage: 
type: 
access: 
mechanism: 


mask_longword 
longword (unsigned) 
read only 
by reference 


Mask that denotes video attributes for the drawn line. The rendition-set 
argument is the address of an unsigned longword that contains a video 
attributes mask. Each bit attribute in this argument causes the corresponding 
attribute to be set in the display. 


Video attributes that can be manipulated in this manner are as follows: 


SMG$M_BLINK 
SMG$M_BOLD 
SMG$M—REVERSE 

SMG$M_UNDERLINE 


Displays blinking characters 

Displays characters in higher-than-normal intensity 

Displays characters in reverse video, that is, using 
the opposite default rendition of the virtual display 

Displays underlined characters 


If the same bit is set in both the rendition-set and rendition-complement 
arguments, the Screen Management Facility applies the rendition-set attribute 
followed by the rendition-complement attribute. Using these two arguments, 
the caller can exercise independent control over each attribute in a single call. 


rendition-complement 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mask that denotes video attributes for the line drawn. The rendition- 
complement argument is the address of an unsigned longword that contains 
a video attributes mask. Each bit attribute in this argument causes the 
corresponding attribute to be set in the display. Video attributes that can be 
manipulated in this manner are the same as for the rendition-set argument. 
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SMG$DRAW_RECTANGLE 


The following table shows the action taken by the Screen Management 
Facility for various combinations of rendition-set and rendition-complement 
attributes. 


Set 

Complement 

Action 

0 

0 

Attribute unchanged 

1 

0 

Attribute on 

0 

1 

Attribute set to complement of default setting 

1 

1 

Attribute off 


DESCRIPTION 

SMG$DRAW_RECTANGLE draws a rectangle in a virtual display, given the 
position of the upper left-hand corner and the lower right-hand comer. The 
characters used to draw the lines making up the rectangle depend on the type 
of terminal. The virtual cursor position does not change. 

CONDITION 

SSS—NORMAL 

Normal successful completion. 

VALUES 

SMG$_INVCOL 

Invalid column number. The specified column is 

RETURNED 

SMG$_INVROW 

outside the virtual display. 


Invalid row number. The specified row is outside 
the virtual display. 


SMG$_WRONUMARG 

Wrong number of arguments. 


SMG$_INVDIS_ID 

Invalid display-id. 


EXAMPLE 


C+ 

C This FORTRAN example program demonstrates the use of 
C SMG$DRAW_RECTANGLE. 

C 

C This routine creates a virtual display and uses SMG$DRAW_RECTANGLE 
C to draw a rectangle inside the bordered virtual display. 

C- 

C+ 

C Include the SMG definitions. In particular, we want SMG$M_BORDER. 
C- 


INCLUDE '($SMGDEF)' 

INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD 
INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$DRAW_RECTANGLE 
INTEGER DISPLAY1, PASTE1, ROWS. COLUMNS, STATUS 


C+ 

C Create a virtual display with a border by calling 
C SMG$CREATE_VIRTUAL_DISPLAY. 

C- 

ROWS = 7 
COLUMNS = 50 

STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS. COLUMNS. DISPLAY1, SMG$M_BORDER) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(7.VAL(STATUS)) 


Use SMG$CREATE_PASTEBOARD to create the pasteboard. 


STATUS = SMG$CREATE_PASTEBOARD (PASTED 
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
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■f 


Using SMGIDRAW.RECTANGLE, 


draw a rectangle inside the bordered region. 


STATUS - SMG$DRAW_RECTANGLE (DISPLAY1. 2, 10, 6, 20) 
IF (.NOT. STATUS) CALL LIB$SIGNAL OiVAL(STATUS)) 


Paste the virtual display by calling SMG$PASTE_VIRTUAL_DISPLAY. 


STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1. PASTE1, 4. 15) 
IF (.NOT. STATUS) CALL LIB$SIGNALOiVAL(STATUS)) 

END 


The output generated by this FORTRAN example is shown in Figure RTL-16. 

Figure RTL-16 Output Generated by FORTRAN Program Calling 
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SMG$EIMABLE_UNSOLICITED—INPUT 
Enable Unsolicited Input 



SMG$ENABLE_UNSOLICITED_INPUT detects unsolicited input and 
calls an AST routine in response. 

FORMAT 

SMG$ENABLE_UNSOLICITED_INPUT 

pasteboard-id, AST-routine 
[, AST-argument] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard for which unsolicited input is being enabled. The 
pasteboard-id argument is the address of an unsigned longword that contains 
the pasteboard identifier. Pasteboard-id is returned by SMG$CREATE_ 
VIRTUAL -PASTEBOARD. 

AST-routine 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: read only 

mechanism: by reference 

The address of an AST routine to be called upon receipt of unsolicited input 
at the terminal. The AST-routine argument is the address of the routine's 
procedure entry mask, that is, the address of the routine itself. 

AST-argument 

VMS Usage: user—arg 
type: longword 

access: read only 

mechanism: by value 

A value to be passed to the AST routine. The AST-argument argument 
contains the value to be passed to the AST routine. 


DESCRIPTION SMG$ENABLE_UNSOLICITED_INPUT detects the presence of unsolicited 
input and calls the AST routine with six arguments: the pasteboard-id, the 
AST-argument, RO, Rl, PC, and PSL. 
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Note that this routine does not read any input characters; it merely calls 
an AST routine to "notify" the application that it should issue a read 
operation with SMG$READ_COMPOSED_JLINE, SMG$READ_KEYSTROKE, 
SMG$READ_STRING or SMG$READ_VERIFY. It is up to you to read the 
unsolicited input. 

SMG$ENABLE_UNSOLICITED_INPUT establishes a mailbox that receives 
messages when terminal-related events occur that require the attention of the 
user image. This mailbox carries status messages, not terminal data, from 
the driver to the user program. This status message is sent to the mailbox 
when there is unsolicited data in the type-ahead buffer. In this case, the 
user process enters into a dialogue with the terminal after an unsolicited data 
message arrives. Once this dialogue is complete, the Screen Management 
Facility reenables the unsolicited data message function on the last I/O 
exchange. Only one message is sent between read operations. 

For more information on terminal/mailbox interaction, see the VAX/VMS I/O 
User's Reference Manual: Part I. 


CONDITION 

VALUES 

RETURNED 


SSS—NORMAL Normal successful completion. 

SMG$_WRONUMARG Wrong number of arguments. 

SMG$_INVPBD_ID Invalid pasteboard-id. 

Any condition values returned by $QIOW. 


EXAMPLE 


For an example of using SMG$ENABLE_UNSOLICITED_INPUT, see the 
example for the routine SMG$DISABLE_BROADCAST_TRAPPING. 
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SMG$END_DISPLAY-UPDATE 
End Display Update 



SMG$END_DISPLAY_UPDATE ends update batching for a virtual 
display. 

FORMAT 

SMG$END_DISPLAY_UPDATE display-id 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display to be affected. The display-id argument is the 
address of a longword that contains the display identifier. 

Display-id is returned by SMG$CREATE—VIRTUAL —DISPLAY. 

DESCRIPTION 

SMG$END_DISPLAY—UPDATE and SMG$BEGIN-DISPLAY-UPDATE 
work together to control the batching of output operations on a given virtual 
display. Each call to SMG$BEGIN_DISPLAY—UPDATE increments a "batch 
count," while each call to SMG$END_DISPLAY—UPDATE decrements this 
count. When the batch count reaches 0, the virtual display is written to the 
screen. 

Calling SMG$END_DISPLAY—UPDATE when the batch count is zero is a 
valid operation; therefore a success status is returned. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_BATWASOFF Successful completion. Note that batching was 

already off. 

SMG$_BATSTIPRO Successful completion. Note that batching is still 

in progress. 

SMG$_INVDIS_ID Invalid display-id. 

SMG$_WRONUMARG Wrong number of arguments. 
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SMG$END_PASTEBOARD_UPDATE 
End Pasteboard Update 

SMG$END_PASTEBOARD_UPDATE ends update batching for a 



pasteboard. 

FORMAT 

SMG$END_PASTEBOARD_UPDATE 

pasteboard-id 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

pasteboard-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard on which the batch count is to be decremented. The 
pasteboard-id argument is the address of an unsigned longword that contains 
the pasteboard identifier. Pasteboard-id is returned by SMG$CREATE_ 
PASTEBOARD. If the batch count reaches 0, all buffered output for the 
specified pasteboard is written out. 

DESCRIPTION 

SMG$END_PASTEBOARD_UPDATE and SMG$BEGIN_PASTEBOARD_ 
UPDATE work together to control the batching of output operations on 
a given pasteboard. Each call to SMG$BEGIN_PASTEBOARD__UPDATE 
increments a "batch count," while each call to SMG$END_PASTEBOARD_ 
UPDATE decrements this count. When the batch count reaches 0, the 
pasteboard is written to the screen. 

Calling SMG$END_PASTEBOARD_UPDATE when the batch count is 0 is a 
valid operation; a success status is returned. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_BATWASOFF Successful completion. Note that batching was 

already off. 

SMG$_BATSTIPRO Successful completion. Note that batching is still in 

progress. 

SMG$_INVDIS__ID Invalid display-id. 

SMG$_WRONUMARG Wrong number of arguments. 
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SMG$ERASE_CHARS—Erase Characters 

SMG$ERASE_CHARS erases characters in a virtual display by 



replacing them with blanks. 

FORMAT 

SMG$ERASE_CHARS display-id ,number-of-chars 

,row-number 
, column-number 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display from which characters will be erased. The 
display-id argument is the address of an unsigned longword that contains 
the display identifier. 

Display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY. 

number-of-chars 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the number of characters to be replaced with blanks. The number- 
of-chars argument is the address of a signed longword integer that contains 
the number of characters to be replaced with blanks. 

row-number 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the row on which the erase operation begins. The row-number 
argument is the address of a signed longword integer that contains the 
number of the row at which the erasure is to begin. 
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column-number 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column on which the erase operation begins. The column- 
number argument is the address of a signed longword integer that contains 
the number of the column at which the erasure is to begin. 


DESCRIPTION SMG$ERASE_CHARS erases characters in a virtual display by replacing 

them with blanks. The remaining text in the display is not moved. An 
erase operation is limited to the specified line. If number-of-chars is greater 
than the number of characters remaining in the line, all characters from the 
specified starting position to the end of the line are erased. This routine 
leaves the virtual cursor at the position of the first character erased. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_INVDIS_ID 

SMG$_WRONUMARG 

SMGS—INVROW 

SMG$_INVCOL 


Normal successful completion. 
Invalid display-id. 

Wrong number of arguments. 
Invalid row. 

Invalid column. 


EXAMPLE 


C+ 

C This FORTRAN example demonstrates the use of SMG$ERASE_CHARS. 

C 

C Include the SMG definitions. In particular, we want SMG$M_BORDER. 

C- 

INCLUDE '(ISMGDEF)' 

INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD 
INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$PUT_CHARS, SMG$ERASE_CHARS 
INTEGER DISPLAY1, PASTE1, ROWS, COLUMNS 

C+ 

C Create a virtual display with a border by calling 
C SMG$CREATE_VIRTUAL_DISPLAY. 

C- 

ROWS = 7 
COLUMNS = 50 

ISTATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS. COLUMNS. DISPLAY1, SMG$M_BORDER) 

C+ 

C Call SMG$CREATE_PASTEBOARD to create the pasteboard. 

C- 


ISTATUS = SMG$CREATE_PASTEBOARD (PASTE!) 


C+ 

C Using SMG$PUT_CHARS, put data in the virtual display. 

C- 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 1 This virtual display has 7 rows and 50 columns.', 2, 1) 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 1 This is a bordered virtual display.', 4, 1) 

ISTATUS = SMG$PUT_CHARS ( DISPLAY!. 

1 ' SMG$PUT_CHARS puts data in this virtual display.', 6, 1) 
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Call SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display. 

ISTATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTEi, 4, 15) 
C+ 

C Erase 4 characters on row 4 starting from character (column) 14 by 
C calling SMG$ERASE_CHARS. This will remove the characters "rder" 

C from the word "bordered". 

C- 

ISTATUS = SMGIERASE.CHARS ( DISPLAY1, 4. 4, 14) 

END 


The initial output generated by this FORTRAN example program is shown in 
Figure RTL-17. 

Figure RTL-17 Output Before the Call to SMG$ERASE_CHARS 
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The output generated after the call to SMG$ERASE_CHARS is shown in 
Figure RTL-18. 
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Figure RTL-18 Output After the Call to SMG$ERASE_CHARS 
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SMG$ERASE_DISPLAY—Erase Virtual 



Display 

SMG$ERASE_DISPLAY erases all or part of a virtual display by 
replacing text characters with blanks. 

FORMAT 

SMG$ERASE_DISPLAY display-id[,start-row] 

[, s tart-column] [, end-ro w] 
[,end-column] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display to be erased. The display-id argument is the 
address of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE_VIRTUAL-DISPLAY. 

start-row 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the row at which the erase operation begins. The start-row 
argument is the address of a signed longword integer that contains the 
number of the row at which the erasure begins. 

If the start-row argument is not specified, start-column is also ignored and 
the entire virtual display is erased. 

start-column 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column at which the erase operation begins. The start-column 
argument is the address of a signed longword integer that contains the 
number of the column at which the erasure begins. 

If the start-column argument is not specified, start-row is also ignored and 
the entire virtual display is erased. 
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end-row 


VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the row at which the erase operation ends, that is, the last row to be 
erased. The end-row argument is the address of a signed longword integer 
that contains the number of the last row to be erased. 


If the end-row argument is not specified, end-column is also ignored and all 
remaining rows in the display are erased. 


end-column 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column at which the erase operation ends, that is, the last 
column to be erased. The end-column argument is the address of a signed 
longword integer that contains the number of the last column to be erased. 


If the end-column argument is not specified, end-row is also ignored and all 
remaining columns in the display are erased. 


DESCRIPTION SMG$ERASE_DISPLAY causes all or part of a virtual display to be erased by 

replacing text characters with blanks. If omitted, the starting positions default 
to 1,1. The ending positions default to the last row or column in the display. 
Thus, to erase the entire virtual display, you need only pass the display-id. 
The cursor position is the first free position after the erased portion. If the 
entire display is erased, the virtual cursor is left at position 1,1. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_INVDIS_ID 

SMGS—INVCOL 

SMG$_INVROW 

SMG$_WRONUMARG 


Normal successful completion. 

Invalid display-id. 

Invalid column number. The specified column is 
outside the virtual display. 

Invalid row number. The specified row is outside 
the virtual display. 

Wrong number of arguments. 


EXAMPLE 


C+ 

C This FORTRAN example program illustrates the use of SMG$ERASE_DISPLAY. 

C- 

INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD 

INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$PUT_CHARS, SMG$ERASE_DISPLAY 

INTEGER DISPLAY1, PASTE1. ROWS, COLUMNS, BORDER 

C+ 

C Call SMG$CREATE_VIRTUAL_DISPLAY to create the virtual 
C display. To give it a border, set BORDER = 1. 

C No border would be BORDER = 0. 

C- 


ROWS = 7 
COLUMNS = 50 
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BORDER 


ISTATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS, COLUMNS, DISPLAY1, BORDER) 

IF (.NOT. ISTATUS) WRITE (6. 900) 'SMG$CREATE_VIRTUAL_DISPLAY', ISTATUS 


C+ 

C Using SMG$CREATE_PASTEBOARD, create the pasteboard. 
C- 


ISTATUS = SMG$CREATE_PASTEBOARD (PASTED 

IF (.NOT. ISTATUS) WRITE (6, 900) 'SMG$CREATE_PASTEBOARD 1 , ISTATUS 


C+ 

C Call SMG$PUT_CHARS to put data in the virtual display. 

C- 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This virtual display has 7 rows and 50 columns.', 2, 1) 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 


1 ' This is a bordered virtual display.', 4, 1) 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' SMG$PUT_CHARS puts data in this virtual display.', 6, 1) 

C+ 

C Paste the virtual display by calling SMG$PASTE_VIRTUAL_DISPLAY. 

C- 



ISTATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15) 
900 FORMAT (' Routine ', A, ' returned a status of ', Z8) 


C+ 

C Call SMG$ERASE_DISPLAY to erase the display from row 2, 
C column 6, through row 4, column 28. 

C- 


ISTATUS = SMG$ERASE_DISPLAY ( DISPLAY1, 
END 


2 . 


6, 4. 28) 



The initial display output by this FORTRAN program is shown in 
Figure RTL-19. 

Figure RTL—19 Initial Output of FORTRAN Program Calling 

SMG$ERASE_DISPLAY 
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This output displayed after the call to SMG$ERASE_DISPLAY is shown in 
Figure RTL-20. 

Figure RTL-20 Output Displayed After the Call to 
SMG$ERASE_DISPLAY 
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SMG$ERASE_LINE—Erase Line 

SMG$ERASE_LINE erases all or part of a line in a virtual display. 


FORMAT 

SMG$ERASE_LINE display-id[,line-number] 

[, column-number] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display to be affected. The display-id argument is 
the address of an unsigned longword that contains the display identifier. 
Display-id is returned by SMG$CREATE_VIRTUAL-DISPLAY. 

line-number 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the line at which the erase operation starts. The line-number 
argument is the address of a signed longword integer that contains the 
number of the row at which the erasure starts. If omitted, column-number is 
also ignored and the current cursor position is used. 

column-number 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column at which the erase operation starts. The column- 
number argument is the address of a signed longword integer that contains 
the number of the column at which the erasure starts. If omitted, row- 
number is also ignored and the current cursor position is used. 

DESCRIPTION 

SMG$ERASE_LINE erases a line from the specified starting position to the 
end of the line. If you do not specify a starting position, SMG$ERASE_LINE 
erases text from the current virtual cursor position to the end of the line. The 
virtual cursor remains at the first blank position after the erased text. 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_INVDIS_ID 

SMGS—INVCOL 

SMGS—INVROW 

SMG$_WRONUMARG 


Normal successful completion. 

Invalid display-id. 

Invalid column number. The specified column is 
outside the virtual display. 

Invalid row number. The specified row is outside 
the virtual display. 

Wrong number of arguments. 


EXAMPLE 


C+ 

C This FORTRAN example program demonstrates the use of 
C SMG$ERASE_LINE. 

C- 

INCLUDE '($SMGDEF)' 

INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD 
INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$PUT_CHARS, 

1 SMG$ERASE_DISPLAY 

INTEGER DISPLAYl, PASTE1. ROWS. COLUMNS 


C+ 

C Use SMG$CREATE_VIRTUAL_DISPLAY to create a virtual display 
C with a border. 

C- 

ROWS = 7 
COLUMNS = 50 

ISTATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS. COLUMNS. DISPLAYl, SMG$M_BORDER) 

IF (.NOT. ISTATUS) WRITE (6. 900) 'SMG$CREATE_VIRTUAL_DISPLAY'. 
1 ISTATUS 

C+ 

C Call SMG$CREATE_PASTEBOARD to create the pasteboard. 

C- 

ISTATUS = SMG$CREATE_PASTEBOARD (PASTED 

IF (.NOT. ISTATUS) WRITE (6. 900) 'SMG$CREATE_PASTEBOARD', 

1 ISTATUS 

C+ 

C Put data in the virtual display by calling SMG$PUT_CHARS. 

C- 


ISTATUS = SMG$PUT_CHARS ( DISPLAYl. 

1 ' This virtual display has 7 rows and 50 columns.', 2, 1) 

ISTATUS = SMG$PUT_CHARS ( DISPLAYl, 

1 ' This is a bordered virtual display.', 4, 1) 

ISTATUS = SMG$PUT_CHARS ( DISPLAYl. 

1 ' SMG$PUT_CHARS puts data in this virtual display.', 6, 

1 1 ) 

C+ 

C Use SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display. 

C- 


ISTATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAYl, PASTE1. 4, 15) 
900 FORMAT (' Routine '.A, ' returned a status of ', Z8) 


C+ 

C Call SMG$ERASE_LINE to erase line 2, and then again to 
C erase the last 4 words on line 4. 

C- 


ISTATUS = SMG$ERASE_LINE ( DISPLAYl. 2, 1) 
ISTATUS = SMG$ERASE_LINE ( DISPLAYl, 4, 9) 
END 
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The initial output generated by the FORTRAN program is shown in 
Figure RTL-21. 


Figure RTL-21 Initial Output Generated by FORTRAN Program 
Calling SMG$ERASE_LINE 
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The output generated after the call to SMG$ERASE_LINE is shown in 
Figure RTL-22. 
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Figure RTL-22 Output Generated After the Call to 
SMG$ERASE_LINE 
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SMG$ERASE_PASTEBOARD—Erase 

Pasteboard 



SMG$ERASE_PASTEBOARD erases a pasteboard; that is, it clears 
the screen. 

FORMAT 

SMG$ERASE_PASTEBOARD pasteboard-id 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

pasteboard-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard to be erased. The pasteboard-id argument is the 
address of an unsigned longword that contains the pasteboard identifier. 
Pasteboard-id is returned by SMG$CREATE_PASTEBOARD. 


DESCRIPTION SMG$ERASE_PASTEBOARD erases the specified pasteboard. The physical 

cursor is left at position 1,1. If there are any virtual displays pasted to the 



pasteboard, they will be redrawn the next time the Screen Management 
Facility is used to output to the pasteboard. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_WRONUMARG Wrong number of arguments. 

SMG$_INVPAS_ID Invalid pasteboard-id. 


EXAMPLE 

O 

C This FORTRAN example program demonstrates how to use 
C SMG$CREATE_VIRTUAL_DISPLAY. 

C- 

IMPLICIT INTEGERS (A-Z) 

CHARACTER*80 OUT.STR.TRIM.STR 

CHARACTER*18 PROMPT /'Please enter data '/ 

SMG$M_B0LD = 1 
SMG$M_REVERSE = 2 
SMG$M_BLINK = 4 
SMG$M_UNDERLINE * 8 
C+ 

C Establish the terminal keyboard as the virtual keyboard 
C by calling SMG$CREATE_VIRTUAL_KEYBOARD. 
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c- 

STATUS = SMG$CREATE_VIRTUAL_KEYBOARD(KEYBOARD.ID,,,) 
IF (.NOT. STATUS) CALL LIB$ST0PC/.VAL(STATUS)) 

C+ 

C Establish the terminal screen as a pasteboard using 
C SMG$CREATE_PASTEBOARD. 

C- 


STATUS = SMG$CREATE_PASTEBOARD (NEW.PID,,,) 

IF (.NOT. STATUS) CALL LIB$STOP C/.VAL (STATUS) ) 
C+ 

C Establish a virtual display region by 
C calling SMG$CREATE_VIRTUAL_DISPLAY. 

C- 


STATUS = SMG$CREATE_VIRTUAL_DISPLAY (5,80,DISPLAY_ID,,,) 
IF (.NOT. STATUS) CALL LIB$ST0P C/.VAL (STATUS) ) 

C+ 

C Paste the virtual display to the screen, starting at 
C row 10, column 15. To paste the virtual display, use 
C SMGlPASTE.VIRTUAL.DISPLAY. 

C- 


STATUS = SMG$PASTE_VIRTUAL_DISPLAY(DISPLAY.ID,NEW.PID,10,15) 
IF (.NOT. STATUS) CALL LIB$ST0P (7.VAL (STATUS) ) 

C+ 

C Prompt the user for input, and accept that input using 
C SMG$READ_STRING. 

C- 


STATUS » SMG$READ_STRING(KEYBOARD_ID.OUT.STR,PROMPT,,,,,,,) 
IF (.NOT. STATUS) CALL LIB$ST0P('/.VAL(STATUS)) 

C+ 

C Clear the screen using SMG$ERASE_PASTEBOARD. 

C- 


STATUS = SMGIERASE.PASTEBOARD (NEW.PID) 

IF (.NOT. STATUS) CALL LIB$ST0P C/.VAL (STATUS)) 
C+ 

C Trim any trailing blanks from the user input 
C by calling STR$TRIM. 

C- 

STATUS = STR$TRIM(TRIM.STR,OUT.STR,STR.LEN) 

IF (.NOT. STATUS) CALL LIB$ST0P C/.VAL (STATUS)) 


C+ 

C Display the data input by the user using SMG$PUT_CHARS 
C and SMG$PUT_LINE. 

C- 


STATUS = SMG$PUT_CHARS(DISPLAY.ID.'You entered: '.,,,,,) 
IF (.NOT. STATUS) CALL LIB$ST0P(7.VAL(STATUS)) 

STATUS = SMGSPUT.LINE(DISPLAY.ID,TRIM.STR(1:STR.LEN),, 

1 SMG$M_REVERSE,0,,) 

IF (.NOT. STATUS) CALL LIB$ST0PC/.VAL(STATUS)) 

END 


This FORTRAN program calls Run-Time Library Screen Management routines 
to format screen output, and to accept and display user input. 
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SMG$FIND_CURSOR_DISPLAY 
Find Display That Contains The Cursor 

SMG$FIND_CURSOR_DISPLAY returns the identifier of the most 



recently pasted virtual display that contains the physical cursor. 

FORMAT 

SMG$FIND_CURSOR_DISPLAY 

pasteboard-id, returned-display-id 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

pasteboard-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard (physical screen) in which the cursor is to be found. 
The pasteboard-id argument is the address of a longword that contains 
the pasteboard identifier. Pasteboard-id is returned by SMG$CREATE_ 
PASTEBOARD. 

returned-display-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Receives the identifier of the display in which the cursor was found. The 
returned-display-id argument is the address of a longword into which is 
written the display identifier. 


DESCRIPTION SMG$FIND_CURSOR_DISPLAY determines which virtual display contains 
the physical cursor on a specified pasteboard, and returns the virtual display's 



identifier. SMG$FIND_CURSOR_DISPLAY returns the display-id of the 
most recently pasted virtual display which contains the physical cursor. If no 
virtual display contains the physical cursor, this routine returns a 0, which is 
an invalid display identifier. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_INVPAS_ID Invalid pasteboard-id. 

SMG$_WRONUMARG Wrong number of arguments. 
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SMG$FLUSH_BUFFER—Flush Buffer 

SMG$FLUSH_BUFFER flushes all buffered output to the terminal 


FORMAT 

SMG$FLUSH_BUFFER pasteboard-id 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

pasteboard-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard to be flushed. The pasteboard-id argument is the 
address of an unsigned longword that contains the pasteboard identifier. 
Pasteboard-id is returned by SMG$CREATE_PASTEBOARD. 

DESCRIPTION 

SMG$FLUSH_BUFFER causes all buffered output to be sent to the terminal 
immediately. The calling program would normally call this routine just before 
performing some cpu-intensive calculations, or whenever the terminal screen 
must be up-to-date. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_WRONUMARG Wrong number of arguments. 

SMG$_INVPAS_ID Invalid pasteboard-id. 
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SMG$GET_BROADCAST_MESSAGE 

Get Broadcast Message 


SMG$GET_BROADCAST_MESSAGE determines whether a 
message has been broadcast to the pasteboard and returns the 
message. 

FORMAT 

SMG$GET_BROADCAST_MESSAGE 

pasteboard-id [, message] 

[, message-length] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS pasteboard-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the terminal to be checked for the presence of a broadcast message. 
The pasteboard-id argument is the address of an unsigned longword 
that contains the pasteboard identifier. Pasteboard-id is returned by 
SMG$CREATE_PASTEBOARD. 

message 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

A string that receives the broadcast message, if such a message is available. 
The message argument is the address of a descriptor that points to the 
storage into which the message text is written. If this argument is omitted, 
the broadcast message is discarded. 

message-length 

VMS Usage: word-signed 
type: word integer (signed) 

access: write only 

mechanism: by reference 

Receives the actual length of the broadcast message. The message-length 
argument is the address of a word into which is written the length of the 
message. 
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DESCRIPTION SMG$GET_BROADCAST_MESSAGE determines whether any broadcast 

messages have been sent to the specified terminal while broadcast trapping 
was enabled, and if so, returns the message in the message argument. 

If no broadcast messages have been sent to the terminal, SMG$GET_ 
BROADCAST-MESSAGE returns the success status SMG$_NO_MORMSG. 


CONDITION 

VALUES 

RETURNED 


SSS—NORMAL 

SMG$_NO_MORMSG 

SMG$_WRONUMARG 

SMG$_INVPAS_ID 


Normal successful completion. 

Successful completion. No more messages to be 
returned. 

Wrong number of arguments. 

Invalid pasteboard-id. 


Any condition values returned by LIB$SCOPY_DXDX. 
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SMG$GET_CHAR_AT_PHYSICAI_CURSOR 

Return Character At Cursor 


SMG$GET_CHAR_AT_PHYSICAI_CURSOR returns the character 

at the current physical cursor position. 

FORMAT 

SMG$GET_CHAR_AT_PHYSICAI_CURSOR 

pasteboard-id .character 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard on which to retrieve the character. The pasteboard- 
id argument is the address of a longword that contains the pasteboard 
identifier. 

Pasteboard-id is returned by SMG$CREATE_PASTEBOARD. 


character 

VMS Usage: byte_unsigned 
type: byte (unsigned) 

access: write only 

mechanism: by reference 

Returned character code. The character argument is the address of an 
unsigned byte into which is written the character's ASCII code. 


DESCRIPTION SMG$GET_CHAR_AT_PHYSICAL_CURSOR returns the character that 
occupies the screen position corresponding to the current physical cursor 
position. 


Note: If the Screen Management Facility has not written to the screen location 
occupied by the physical cursor, then the contents of that position are 
unknown. In this case, the hexadecimal value FF is returned. 

If the returned character has an ASCII value less than 20 (hexadecimal), then 
it is not a printable character. Rather, it is an internal terminal-independent 
code denoting what should be displayed at that position (for example, an 
element of the line-drawing character set). Do not attempt to use this code 
for subsequent output operations. 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL Normal successful completion. 

SMG$_WRONUMARG Wrong number of arguments. 

SMG$_INVPAS_ID Invalid pasteboard-id. 


April 1986 
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SMG$GET_DISPLAY_ATTR—Get Display 

Attributes 



SMG$GET_DISPLAY_ATTR returns attributes associated with a 
virtual display. 

FORMAT 

SMG$GET_DISPLAY_ATTR display-id 

[, height] [, width] 

[, display-attributes] 

[, video-attributes] 

[, char-set] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display for which information is requested. The display- 
id argument is the address of an unsigned longword that contains the display 
identifier. Display-id is returned by SMG$CREATE_VIRTUAL —DISPLAY. 

height 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Receives the number of rows in the display. The height argument is the 
address of a signed longword integer into which the height is written. 

width 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Receives the number of columns in the display. The width argument is the 
address of a signed longword integer into which is written the number of 
columns in the display. 
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display-attributes 


VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Receives the current default display attributes (for example, SMG$M— 
BORDER). The display-attributes argument is the address of an unsigned 
longword into which the current display attributes are written. 


video-attributes 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Receives the current default video attributes. The video-attributes argument 
is the address of an unsigned longword into which the current video attributes 
are written. 


Valid video attributes are as follows: 


SMG$M_BLINK 
SMG$M_BOLD 
SMG$M—REVERSE 

SMG$M_UNDERLINE 


Displays blinking characters 

Displays characters in higher-than-normal intensity 

Displays characters in reverse video, that is, using 
the opposite default rendition of the virtual display 

Displays underlined characters 


char-set 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Specifies the default character set for all text in this virtual display. The 
char-set argument is the address of an unsigned longword that specifies the 
character set. At this time, the only valid value is SMG$C_ASCII, which is 
also the default. 


DESCRIPTION SMG$GET_DISPLAY—ATTR returns the attributes of a virtual display. 


CONDITION SS$_NORMAL 

VALUES SMG$_INVDIS_ID 

RETURNED smg$_wronumarg 


Normal successful completion. 
Invalid display-id. 

Wrong number of arguments. 


April 1986 
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SMG$GET_KEY_DEF—Get Key Definition 

SMG$GET_KEY_DEF returns the key definition for a specified key. 


FORMAT SMG$GET_KEY_DEF key-table-id,tkey-name 

[,if-state] [, attributes] 

[, equiv-string] [, state-string] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


ARGUMENTS key-table-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the key table from which you are extracting a definition. The key- 
table-id argument is the address of an unsigned longword that contains 
the key table identifier. Key-table-id is returned by SMG$ CREATE-KEY- 
TABLE. 

key-name 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Specifies the name of the key associated with the definition. The key-name 
argument is the address of a descriptor pointing to the key name. 

Table 3-1 lists the valid key names. 


if-state 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Specifies the current state name in effect after the key is pressed. The if-state 
argument is the address of a descriptor pointing to the state name. 


See SMG$ADD_KEY—DEF for more information. 


attributes 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: write only 
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mechanism: by reference 

Receives the attributes bit mask for this key definition. The attributes 
argument is the address of a longword into which is written the bit mask 
describing the key's attributes. 

Valid values are as follows: 


SMG$M_KEY_NOECHO 


SMG$M_KEY__TERMINATE 


SMG$M_KEY_LOCKST ATE 


SMG$M_KEY_PROTECTED 


If set, this bit specifies that equiv_ 
string is not to be echoed when 
this key is pressed. If clear, equiv_ 
string is echoed. If SMG$M_KEY_ 
TERMINATE is not set, SMG$M_ 
KEY_NOECHO is ignored. 

If set, this bit specifies that when 
this key is pressed (as qualified by 
if-state), the input line is complete 
and more characters should not be 
accepted. If clear, more characters 
may be accepted. 

If set, and if state-string is 
specified, the state name specified 
by state-string remains the current 
state until explicitly changed by 
a subsequent keystroke whose 
definition includes a state-string. If 
clear, the state name specified by 
state-string remains in effect only 
for the next defined key stroke. 

If set, this bit specifies that this 
key definition cannot be modified or 
deleted. If clear, the key definition 
can be modified or deleted. 


equiv-string 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Receives the equivalence string for this key definition, 
argument is the address of a descriptor pointing to the 
written the equivalence string. 


The equiv-string 

storage into which is 


state-string 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Receives the new state name, if any, which is set by this key definition. The 
state-string argument is the address of a descriptor pointing to the storage 
into which is written the new state string. 


DESCRIPTION SMG$GET_KEY_DEF returns the key definition associated with a specified 

key-name and if-state. 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_INVKTB_ID 

SMG$_KEVNOTDEF 

SMG$_WRONUMARG 


Normal successful completion. 
Invalid key-table-id. 

Key not defined. 

Wrong number of arguments. 


Any condition values returned by LIB$SCOPY_DXDX. 
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SMG$GET_KEYBOARD_ATTRIBUTES 
Get Keyboard Attributes 



SMG$GET_KEYBOARD_ATTRIBUTES gets information about a 
virtual keyboard and leaves it in a user-supplied area: the keyboard 
information table (KIT). 

FORMAT 

SMG$GET_KEYBOARD_ATTRIBUTES keyboard-id 

,p-kit 
,p-kit-size 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

keyboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Keyboard identifier. The keyboard-id argument is the address of an unsigned 
longword containing the identification of the virtual keyboard from which 
to read. A virtual-keyboard is created by calling the SMG$CREATE_ 

VIRTUAL-KEYBOARD routine. 

p-kit 

VMS Usage: address 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Address of the keyboard information table. The p-kit argument is the address 
of an unsigned longword that contains a pointer to the keyboard information 
table (KIT). The KIT is a byte block whose size and field references are 
described in $SMGDEF. It is the caller's responsibility to allocate the correct 
size block and to pass its address to this routine. 

The values in the p-kit can be accessed through the following symbolic 
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names: 

SMG$L_DEVCHAR 

SMG$L_DEVDEPEND 

SMG$L_DEVDEPEND2 

SMG$B_DEVCLASS 

SMG$B_REC ALL _SIZE 
SMG$B_PHY_DEVTYPE 

SMG$B_TYPEAHEAD_CHAR 

SMG$W_WIDTH 

SMG$W_TYPEAHEAD_COUNT 


Device characteristics (longword) 
Specific characteristics 1 (longword) 
Specific characteristics 2 (longword) 

Device class (byte) — for example, 
DC$_TERM 

Size of recall buffer (byte) (*) 

Physical device type (byte) — for 
example, DT$_VT100 

First character in type-ahead buffer 
(byte) (*) 

Terminal width (word) 

Number of characters in type-ahead 
buffer (word) (*) 


Items marked with an asterisk (*) will be zero unless the device is a terminal 
(DEVCLASS = DC$_TERM). 


p-kit-size 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Size of the keyboard information table. The p-kit-size argument is the 
address of an unsigned longword containing the size of the KIT in bytes. 


The size you specify must be exact. You can specify this size with the 
symbolic constant SMG$S_KEYBOARD_INFO—BLOCK. 


DESCRIPTION SMG$GET—KEYBOARD-ATTRIBUTES retrieves information about a virtual 

keyboard and leaves this information in the keyboard information table (KIT). 
The KIT is a user-supplied area consisting of a byte block. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_INVARG 

SMG$_INVKBD_ID 


Normal successful completion. 
KIT is the wrong size. 

Invalid keyboard-id. 
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SMG$GET_NUMERIC_DATA 
Get Numeric Terminal Data 



SMG$GET_NUMERIC_DATA accesses TERMTABLE.EXE and 
returns the numeric sequence that causes a terminal to perform 
a specified operation. 

FORMAT 

SMG$GET_NUMERIC_DATA 

termtable-address,request-code 
, buffer-address 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

termtable-address 

VMS Usage: address 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the address of the TERMTABLE entry for the desired terminal. The 
termtable-address argument is the address of an unsigned longword that 
contains the address of TERMTABLE information. 

Before calling SMG$GET_NUMERIC_DATA, you must obtain this terminal 
table address by calling either SMG$INIT_TERM —TABLE or SMG$INIT_ 
TERM —TABLE _BY_TYPE. 

request-code 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Request code which specifies the desired capability. The request-code 
argument is a signed longword constant containing this request code. The 
request code is of the form SMG$K_code where code corresponds to a 
keyword in the terminal capabilities table, for example, ANSI—CRT. 

See Tables 3-2, 3-3, and 3-4 in Part I of this manual for valid capability 
fields. 
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buffer-address 

VMS Usage: address 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Address of the first byte of the longword to which SMG$GET_NUMERIC— 
DATA writes the numeric capability data. The buffer-address argument is an 
unsigned longword which contains the address of this buffer. 

DESCRIPTION 

SMG$GET_NUMERIC_DATA extracts the requested numeric information 
from a specified terminal table. Before calling SMG$GET_NUMERIC_DATA, 
you must obtain that terminal table address by calling either SMG$INIT_ 
TERM—TABLE or SMG$INIT_TERM —TABLE _BY_TYPE. 

CONDITION 

VALUES 

RETURNED 

SMGS—INVTERTAB Invalid terminal table address. 

SMGS—INVREQCOD Invalid request code. 

SS$_NORMAL Normal successful completion. 
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SMG$GET_PASTEBOARD_ATTRIBUTES 
Get Pasteboard Attributes 



SMG$GET_PASTEBOARD_ATTRIBUTES gets pasteboard 
attributes and stores them in the pasteboard information table. 

FORMAT 

SMG$GET_PASTEBOARD_ATTRIBUTES 

pasteboard-id , pb-info-table 
,pb-info-table-size 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

pasteboard-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard for which information is requested. The pasteboard- 
id argument is the address of an unsigned longword that contains the 
pasteboard identifier. 

Pasteboard-id is returned by SMG$CREATE_VIRTUAL—PASTEBOARD. 

pb-info-table 

VMS Usage: vector—byte_unsigned 

type: byte (unsigned) 

access: write only 

mechanism: by reference, array reference 

Receives the pasteboard attributes. The pb-info-table argument is the address 
of an array of unsigned bytes into which is written the pasteboard attributes. 

The values in the pb-info-table can be accessed through the following 
symbolic names: 

SMG$L_DEVCHAR Device characteristics (longword) 

SMG$L_DEVDEPEND Specific characteristics 1 (longword) 

SMG$I_DEVDEPEND2 Specific characteristics 2 (longword) 

SMG$B_DEVCLASS Device class (byte)— for example, DC$_TERM 
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SMG$B_SMG_DEVTYPE 


SMG$B_PHY_DEVTYPE 


SMG$B_ROWS 

SMG$W_WIDTH 

SMG$B_COLOR 


SMG$B_PARITY 

SMG$W_SPEED 

SMG$W_FILL 

SMG$W_CURSOR_ROW 
SMG$W_CURSOR_COL 
SMGSl_CURSOR_DID 


Internal SMG device type (byte). The four possible 

values for SMG$B_SMG_DEVTYPE are: 

SMG$K_UNKNOWN 

SMG$K_VTFOREIGN 

SMG$K_HARDCOPY 

SMG$K_VTTERMT ABLE 

Physical device type (byte)—for example, DT$_ 
VT100. The possible values for SMG$B_PHY_ 
DEVTYPE are defined in $TTDEF in STARLET. 

Number of rows on device (byte) 

Terminal width (word) 

Color setting (byte). The three possible values for 
SMG$B_COLOR are: 

SMG$C_WHITE 

SMG$C_BLACK 

SMG$C_UNKNOWN 

Parity attributes (byte)—this field is zero if the 
device is not a terminal 

Terminal speed (word)—this field is zero if the 
device is not a terminal 

Fill characteristics (word)—this field is zero if the 
device is not a video terminal 

Row containing physical cursor (word) 

Column containing physical cursor (word) 

Display id of topmost display containing physical 
cursor (longword) 


pb-info-table-size 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the number of bytes in the pb-info-table. The pb-info-table-size 
argument is the address of an unsigned longword that contains the size (in 
bytes) of the pb-info-table. 


The size you specify must be exact. You can specify this size with the 
symbolic constant SMG$S_PASTEBOARD_INFO_BLOCK. 


DESCRIPTION SMG$GET_PASTEBOARD_ATTRIBUTES gets pasteboard attributes and 

stores them in the pasteboard information table. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_INVARG 

SMG$_WRONUMARG 


Normal successful completion. 

Incorrect size specified in pb-info-table-size. 
Wrong number of arguments. 
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SMG$GET_PASTING_INFO—Return 

Pasting 

Information 



Provided that the specified virtual display is currently pasted, the 
row and column of the pasting are returned. 

FORMAT 

SMG$GET_PASTING_INFO display-id 

,pasteboard-id 
, pasted-flag 
[, pasteboard-ro w] 
[,pasteboard-col] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Identifier of the virtual display to be examined. The display-id argument is 
the address of an unsigned longword containing the identifier of this virtual 
display. 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Identifier of the pasteboard on which the virtual display is pasted. The 
pasteboard-id argument is the address of an unsigned longword containing 
the identifier of this pasteboard. 

pasted-flag 

VMS Usage: boolean 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Flag indicating the status of the specified virtual display with respect to the 
specified pasteboard. The pasted-flag argument is the address of an unsigned 
longword indicating this status. 
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If the pasted-flag argument is set to 1, the virtual display specified by 
display-id is pasted to the pasteboard specified by the pasteboard-id 
argument. If pasted-flag is zero, the virtual display is not pasted to the 
specified pasteboard. 

pasteboard-row 

VMS Usage: longword_signed 
type: longword (signed) 

access: write only 

mechanism: by reference 

Row of the pasteboard that contains row 1 of the specified virtual display. 
The optional pasteboard-row argument is the address of a signed longword 
containing the row number of the pasteboard row that contains the first row 
of the virtual display. 

pasteboard-col 

VMS Usage: longword—signed 
type: longword (signed) 

access: write only 

mechanism: by reference 

Column of the pasteboard that contains column 1 of the specified virtual 
display. The optional pasteboard-col argument is the address of a signed 
longword containing the column number of the pasteboard column that 
contains the first column of the virtual display. 

DESCRIPTION 

SMG$GET_PASTING—INFO first checks to see if the virtual display 
specified by display-id is pasted with respect to the pasteboard specified by 
pasteboard-id. If this virtual display is pasted with respect to the pasteboard, 
SMG$GET_PASTING—INFO returns the row and column numbers of the 
pasteboard that correspond to row and column 1 of the pasted virtual display. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_INVDIS_ID Invalid display-id. 

SMG$_INVPAS_ID Invalid pasteboard-id. 

SMG$_WRONUMARG Wrong number of arguments. 

SMG$_ILLBATFNC Display is batched. 
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SMG$GET_TERM_DATA—Get Terminal 

Data 



SMG$GET_TERM_DATA accesses TERMTABLE.EXE and returns 
the character sequence that causes a terminal to perform a specified 
operation. 

FORMAT 

S MG$G ET_TE R M_D AT A termtable-address 

jequest-code 
, max-buffer-length 
,return-length 
, buffer-address 
[, input-argument- vector] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

termtable-address 

VMS Usage: address 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the address of the TERMTABLE entry for the desired terminal. The 
termtable-address argument is the address of an unsigned longword that 
contains the address of TERMTABLE information. 

Termtable-address is returned by SMG$INIT_TERM_TABLE or SMG$INIT_ 
TE RM_T ABLE_B Y_T YPE. 

request-code 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Longword constant of the form SMG$K_code, where code is the name of 
the desired capability field. The request-code argument is the address of an 
unsigned longword that contains the request code. 

See Tables 3-2, 3-3, and 3-4, in Part I of this manual for valid capability 
fields. 
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max-buffer-length 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Maximum length of the buffer into which the requested capability data 
is written. The max-buffer-length argument is the address of a signed 
longword integer that contains the maximum number of bytes that can be 
written into the buffer. 

return-length 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Receives the number of bytes actually written into the buffer. The return- 
length argument is the address of a signed longword integer into which is 
written the number of bytes transferred into the buffer. 

buffer-address 

VMS Usage: address 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Address of the first byte of the buffer which is to receive the capability data. 
The buffer-address argument is an unsigned longword that contains the 
address of the buffer. 


input-argument-vector 

VMS Usage: address 

type: longword (unsigned) 

access. read only 

mechanism: by reference, array reference 

Address of a list of longwords used for capabilities that require a variable 
number of arguments, and for those that require substitution or arithmetic 
operations on an argument. The input-argument-vector argument is the 
address of an array of unsigned longwords that contains capability arguments. 
The first longword must contain the number of arguments that follow. 


DESCRIPTION SMG$GET_TERM_DATA should be used only when you perform direct 

(non-SMG$) I/O to terminals. It accesses the TERMTABLE.EXE entry for the 
specified type of terminal and returns the character sequence that performs 
the specified operation. It is up to you to send this character sequence to the 
terminal. 


CONDITION 

VALUES 

RETURNED 


SSS—NORMAL 

SMG$_INVTERTAB 

SMG$_INVREQCOD 


Normal successful completion. 
Invalid terminal table address. 
Invalid request code. 
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SMG$HOME_CURSOR—Home Cursor 

SMG$HOME_CURSOR moves the virtual cursor to the specified 
corner of a virtual display. 


FORMAT SMG$HOME_CURSOR display-id [.position] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


ARGUMENTS display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display in which the virtual cursor is moved. The 
display-id argument is the address of a longword that contains the display 
identifier. Display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY. 


position 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the point to which the virtual cursor moves. The position argument 
is the address of a longword that contains the position code. 

Valid codes for position are as follows: 


Code 

Meaning 

SMG$C_UPPER_LEFT 

Row 1 column 1 (the upper left-hand corner). 
This is the default if position is not specified. 

SMG$C_LOWER_LEFT 

Row n column 1 (where n is the number 
of rows in the display. That is, the lower 
left-hand corner. It is useful to specify 
this position when accepting input for an 
upward-scrolling virtual display). 

SMG$C_UPPER_RIGHT 

Row 1 column m (where m is the number of 
columns in the display. That is, the upper 
right-hand corner). 

SMG$C_LOWER_RIGHT 

Row n column m (where n is the number of 
rows and m is the number of columns in the 
display. That is, the lower right-hand corner). 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


SMG$HOME_CURSOR moves the virtual cursor to a corner of the specified 
virtual display, according to the code specified in the position argument. The 
caller need not know the dimensions of the virtual display. 


SS$_NORMAL 

SMG$_INVDIS_ID 

SMG$_WRONUMARG 

SMGS—INVARG 


Normal successful completion. 
Invalid display-id. 

Wrong number of arguments. 
Invalid argument. 
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SMG$IIUIT 

-TERM-TABLE—Initialize 

Terminal Table 


SMG$INIT_TERM_TABLE initializes the TERMTABLE database for 
the terminal named, so that subsequent calls to SMG$GET_TERM_ 
DATA can extract information and command strings for 
that terminal. 

FORMAT 

SMG$INIT_TERM_TABLE terminal-name, 

term-en try-address 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

terminal-name 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Specifies the name of the terminal. The terminal-name argument is the 
address of a descriptor pointing to the terminal name. The name must be an 
entry in TERMTABLE.EXE 


term-entry-address 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Address of the entry for a particular type of terminal in TERMTABLE.EXE. 
The term-entry-address argument is the address of an unsigned longword 
that contains the address of TERMTABLE information. 

You use this address when calling the SMG$GET_TERM_DATA procedure 
for that type of terminal. Term-entry-address is returned by SMG$INIT_ 
TERM-TABLE or SMG$INIT_TERM_TABLE_BY—TYPE. 


DESCRIPTION SMG$INIT—TERM—TABLE initializes the TERMTABLE database for the 

terminal named, so that subsequent calls to SMG$GET_TERM_DATA can 
extract information and command strings for that terminal. This routine 
should be used only when you perform direct (non-SMG$) I/O to terminals. 

SMG$INIT_TERM_TABLE first searches for TERMTABLE in the area 
logically named TERM$TABLOC. If TERMTABLE is not found there, the 
routine searches the global section SMG$TERMTABLE. 
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CONDITION 

SS$_NORMAL 

Normal successful completion. 

VALUES 

SMG$_PRISECMAP 

Successful completion. The definition was found in 

RETURNED 


a private TERMTABLE. 


SMG$_GBLSECMAP 

Successful completion. The definition was found in 
the global TERMTABLE. 


SMGS—UNDTERNOP 

Undefined terminal. No definition was found for the 
terminal and no private TERMTABLE was found. 


SMG$_UNDTERNOS 

Undefined terminal. No definition was found for the 
terminal and no system TERMTABLE was found. 


SMG$_UNDTERNAM 

Undefined terminal name. 
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SMG$IIMIT_TERM—TABLE—BY—TYPE 
Initialize TERMTABLE By VMS Terminal 
Type 


SMG$INIT_TERM_TABLE_BY_TYPE initializes the TERMTABLE 
database for the terminal named, so that subsequent calls to 
SMG$GET_TERM_DATA can extract information and command 
strings for that terminal. 

FORMAT 

SMG$INIT_TERM_TABLE_BY_TYPE 

terminal-type , term-entry-address 
[, terminal-name] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS terminal-type 

VMS Usage: byte_signed 
type: byte integer (signed) 

access: read only 

mechanism: by reference 

The device type of the terminal, as designated by a VMS symbolic terminal 
type or by another value returned by the $GETDVI system service. The 
terminal-type argument is the address of a signed byte integer that contains 
the terminal type. 


term-entry-address 

VMS Usage: address 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Address of the entry for a particular type of terminal in TERMTABLE.EXE. 
The term-entry-address argument is the address of an unsigned longword 
into which is written the address of a terminal entry. 

You use this address when calling the SMG$GET_TERM_DATA procedure 
for that type of terminal. 


terminal-name 

VMS Usage: device_name 
type: character string 

access: write only 

mechanism: by descriptor 

A string into which is written the terminal name associated with the device 
type. The terminal-name argument is the address of a descriptor pointing to 
the storage into which the terminal name is written. 
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DESCRIPTION SMG$INIT_TERM_TABLE_BY_TYPE initializes the TERMTABLE database 

for the terminal type specified, so that subsequent calls to SMG$GET_ 
TERM—DATA can extract information and command strings for that type 
of terminal. This routine should be used only when you perform direct 
(non-SMG$) I/O to terminals. 

SMG$INIT_TERM_TABLE_BY_TYPE first searches for TERMTABLE in the 
area logically named TERM$TABLOC. If TERMTABLE is not found there, the 
routine searches the global section SMG$TERMTABLE. 


CONDITION SS$_NORMAL 

VALUES SMG$_PRISECMAP 

RETURNED 

SMG$_GBLSECMAP 

SMG$_UNDTERNOP 

SMG$_UNDTERNOS 

SMG$_UNDTERNAM 


Normal successful completion. 

Successful completion. The definition was found in 
a private TERMTABLE. 

Successful completion. The definition was found in 
the global TERMTABLE. 

Undefined terminal. No definition was found for the 
terminal and no private TERMTABLE was found. 

Undefined terminal. No definition was found for the 
terminal and no system TERMTABLE was found. 

Undefined terminal name. 
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SMG$INSERT_CHARS—Insert Characters 

SMG$INSERT_CHARS inserts characters into a virtual display. 


FORMAT 

SMG$INSERT__CHARS display-id,string ,row 

, column [,rendition-set] 

[, rendition-complement] 

[, char-set] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display affected. The pasteboard-id argument is the 
address of an unsigned longword that contains the pasteboard identifier. 
Display-id is returned by SMG$CREATE_VIRTUAL-DISPLAY. 

string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

The character string to be inserted. The string argument is the address of a 
descriptor that points to the string to be inserted. 

row 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

The row position at which to begin the insertion. The row argument is the 
address of a signed longword integer that contains the row number. 

column 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

The column position at which to begin the insertion. The column argument 
is the address of a signed longword integer that contains the column number. 
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rendition-set 


VMS Usage: 
type: 
access: 
mechanism: 


mask_longword 
longword (unsigned) 
read only 
by reference 


A mask which denotes video attributes for the characters inserted. The 
rendition-set argument is the address of an unsigned longword that contains 
a video attributes mask. Each bit attribute in this argument causes the 
corresponding attribute to be set in the display. 


Video attributes which can be manipulated in this manner are as follows: 


SMG$M_BLINK 
SMG$M_BOLD 
SMG$M_RE VERSE 

SMG$M_UNDERLINE 


Displays blinking characters 

Displays characters in higher-than-normal intensity 

Displays characters in reverse video, that is, using 
the opposite default rendition of the virtual display 

Displays underlined characters 


If the same bit is set in both the rendition-set and rendition-complement 
arguments, the Screen Management Facility applies the rendition-set 
attribute followed by the rendition-complement attribute. Using these two 
arguments, the caller can exercise independent control over each attribute in 
a single call. 


rendition-complement 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


A mask which denotes video attributes for the characters inserted. The 
rendition-complement argument is the address of an unsigned longword 
that contains a video attributes mask. Each bit attribute in this argument 
causes the corresponding attribute to be set in the display. Video attributes 
which can be manipulated in this manner are the same as those for the 
rendition-set argument. 


The following table shows the action taken by the Screen Management 
Facility for various combinations of rendition-set and rendition-complement 
attributes. 


Set 

Complement 

Action 

0 

0 

Attribute unchanged 

1 

0 

Attribute on 

0 

1 

Attribute set to complement of default setting 

1 

1 

Attribute off 


char-set 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the default character set for all text in this virtual display. The 
char-set argument is the address of an unsigned longword that contains 
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the character set code. At this time, the only valid value is SMG$C_ASCII, 
which is also the default. 


DESCRIPTION 

SMG$INSERT_CHARS inserts the specified character string at the row and 
column positions specified. Characters to the right of the insertion are shifted 
to the right. Note that any characters which do not fit on the current line are 
discarded. The virtual cursor remains at the character position following the 
last character inserted. 

CONDITION 

SSS—NORMAL 

Normal successful completion. 

VALUES 

SMG$_INVROW 

Invalid row. 

RETURNED 

SMG$_INVCOL 

Invalid column. 


SMG$_INVDIS—ID 

Invalid display-id. 


SMG$_WRONUMARG 

Wrong number of arguments. 


SMG$_INVARG 

Unrecognized rendition code. 


LIB$_INVSTRDES 

Invalid string descriptor. 


EXAMPLE 


C+ 

C This FORTRAN example program illustrates the use of SMG$INSERT_CHARS. 

C- 

INCLUDE '($SMGDEF)' 

INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD 
INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$PUT_CHARS, 

1 SMG$ERASE_DISPLAY 

INTEGER DISPLAY1, PASTE1, ROWS, COLUMNS 

C+ 

C Use SMG$CREATE_VIRTUAL_DISPLAY to create a virtual display 
C with a border. 

C- 

ROWS = 7 
COLUMNS = 50 

ISTATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER) 

IF (.NOT. ISTATUS) WRITE (6, 900) 1 SMG$CREATE_VIRTUAL_DISPLAY', 

1 ISTATUS 

C+ 

C Call SMG$CREATE_PASTEBOARD to create the pasteboard. 

c- 

ISTATUS = SMG$CREATE_PASTEBOARD (PASTED 

IF (.NOT. ISTATUS) WRITE (6. 900) 'SMG$CREATE_PASTEBOARD'. 

1 ISTATUS 

C+ 

C Put data in the virtual display by calling SMG$PUT_CHARS. 

C- 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This virtual display has 7 rows and 50 columns.', 2, 1) 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This is a bordered virtual display.', 4, 1) 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' SMG$PUT_CHARS puts data in this virtual display.', 6, 

1 D 


C+ 

C Use 
C- 


SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display. 
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ISTATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15) 
900 FORMAT (' Routine ', A, ' returned a status of ', Z8) 

Call SMG$INSERT_CHARS to add a row 1 of text, starting at col umn 6. 

C Underline these characters. 

C- 

ISTATUS = SMG$INSERT_CHARS ( DISPLAY1, 

1 'This is a new row.', 1, 6. SMG$M_UNDERLINE) 

C+ 

C Calling SMG$INSERT_CHARS again, add text to row 6. 

C Note that there will be some characters that will no 
C longer fit on the line. They will be discarded. The 
C new text will be bolded. 

C- 

ISTATUS = SMGSINSERT.CHARS ( DISPLAY1, 

1 'to this bordered display.', 6, 28, SMG$M_BOLD) 

END 


The output generated by this FORTRAN program before the call to 
SMG$INSERT_CHARS is shown in Figure RTL-23. 

Figure RTL-23 Output Generated by FORTRAN Program Before 
the Call to SMG$INSERT_CHARS 




V. 

ZK-4143-85 



The output generated by this FORTRAN program after the call to 
SMG$INSERT_CHARS is shown in Figure RTL-24. 
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Figure RTL-24 Output Generated by FORTRAN Program After 
the Call to SMG$INSERT_CHARS 
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SMG$INSERT_LINE—Insert Line 



SMG$INSERT_LINE inserts a line into a virtual display and scrolls 
the display. 

FORMAT 

SMG$ 1NSE RT_LI N E display-id,line-number[, string] 

[, direction] [, rendition-set] 

[, rendition-complement] 

[, wrap-flag] [, char-set] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display affected. The display-id argument is the address 
of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY. 

line-number 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the line number at which the string is inserted and at which point 
scrolling begins. The line-number argument is the address of a signed 
longword integer that contains the line number. 

string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

The character string to be inserted by SMG$INSERT__LINE. The string 
argument is the address of a descriptor pointing to this string. 
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direction 


VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the scrolling direction. The direction argument is the address of a 
longword that contains the direction code. Valid values are SMG$M_UP and 
SMG$M_DOWN. SMG$M_UP is the default. 


rendition-set 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Mask that denotes video attributes for the drawn line. The rendition-set 
argument is the address of an unsigned longword that contains a video 
attributes mask. Each bit attribute in this argument causes the corresponding 
attribute to be set in the display. 


Video attributes that can be manipulated in this manner are as follows: 


SMG$M_BLINK 

SMG$M_BOLD 

SMG$M_REVERSE 

SMG$M_UNDERLINE 


Displays blinking characters 

Displays characters in higher-than-normal intensity 

Displays characters in reverse video, that is, using 
the opposite default rendition of the virtual display 

Displays underlined characters 


If the same bit is set in both the rendition-set and rendition-complement 
arguments, the Screen Management Facility applies the rendition-set attribute 
followed by the rendition-complement attribute. Using these two arguments, 
the caller can exercise independent control over each attribute in a single call. 


rendition-complement 


VMS Usage: 
type: 
access: 
mechanism: 


mask_longword 
longword (unsigned) 
read only 
by reference 


Mask that denotes video attributes for the line drawn. The rendition- 


complement argument is the address of an unsigned longword that contains 
a video attributes mask. 


Each bit attribute in this argument causes the corresponding attribute to be 
set in the display. Video attributes that can be manipulated in this manner 
are the same as for the rendition-set argument. 

The following table shows the action taken by the Screen Management 
Facility for various combinations of rendition-set and rendition-complement 
attributes. 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


Set 

Complement 

Action 

0 

0 

Attribute unchanged 

1 

0 

Attribute on 

0 

1 

Attribute set to complement of default setting 

1 

1 

Attribute off 


wrap-flag 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the action to take if the text does not fit on the line. The wrap-flag 
argument is the address of an unsigned longword that contains the flag. Zero 
specifies no wrap (the default) while 1 specifies wrap. 


char-set 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the default character set for all text in this virtual display. The 
char-set argument is the address of a longword that contains the character set 
code. At this time, the only valid value is SMG$C_ASCII, which is also the 
default. 


SMG$INSERT_LINE lets you insert a line into a virtual display at a location 
other than the first or last line. Existing lines are scrolled in the specified 
direction to create an open space. If you specify a string argument, that 
string is written in the space created; otherwise, the new line remains blank. 

If the string does not span the width of the display, it is padded with blanks. 

If wrap-flag is set to 1 and the specified string is longer than the width of the 
virtual display, SMG$INSERT_LINE scrolls another line and writes the excess 
characters in the created space. If wrap-flag is 0, any excess characters are 
discarded. The virtual cursor remains at the character position following the 
last character written. 

See SMG$PUT_LINE to add lines and scroll at the first or last line in a virtual 
display. 


SS$_NORMAL 

SMG$_INVDIS_ID 

SMG$_WRONUMARG 

SMG$_INVROW 

SMG$_INVCOL 

SMG$_INVARG 


Normal successful completion. 

Invalid display-id. 

Wrong number of arguments. 

Invalid row. 

Invalid column. 

Invalid argument. The specified direction is not up 
or down. 
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lognam-flag 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies whether filespec is to be treated as a logical name. The lognam-flag 
argument is the address of an unsigned longword that contains the flag. If 
set, lognam-flag specifies that filespec should be translated, but if this is not 
possible, that the null string be used. 

DESCRIPTION 

SMG$LOAD_KEY_DEFS opens and reads a file containing DEFINE/KEY 
commands and calls SMG$DEFINE_KEY for each command line in the file. 
Use of SMG$LOAD_KEY_DEFS requires that the calling program be run 
under the DCL command language interpreter. This routine signals any 
errors encountered while processing command lines. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_FILTOOLON File specification is too long (over 255 characters). 

Any condition values returned by SMG$DEFINE_KEY. 

Any condition values returned by $OPEN. 
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SMG$MOVE—VIRTUAL—DISPLAY—Move 

Virtual 

Dis- 

play 



SMG$MOVE_VIRTUAl_DISPLAY relocates a virtual display on a 

pasteboard and preserves the pasting order. 

FORMAT 

SMG$MOVE_VIRTUAI_DISPLAY 

display-id, pasteboard-id 
,pasteboard-row 

,pasteboard-column [, top-display-id] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display to be moved. The display-id argument is the 
address of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE-VIRTUAL-DISPLAY. 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard on which the movement is to take place. The 
pasteboard-id argument is the address of an unsigned longword that contains 
the pasteboard identifier. 

Pasteboard-id is returned by SMG$CREATE—PASTEBOARD. 

pasteboard-row 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the row of the pasteboard that is to contain row 1 of the specified 
virtual display. The pasteboard-row argument is the address of a signed 
longword integer that contains the row number. 
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pasteboard-column 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column of the pasteboard that is to contain column 1 of the 
specified virtual display. The pasteboard-column argument is the address of 
a signed longword integer that contains the column number. 

top-display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Identifier of the virtual display under which the unpasted display-id will be 
pasted. The top-display-id argument is the address of an unsigned longword 
containing the specified virtual display identifier. Note that the use of the 
top-display-id argument is only valid when the virtual display specified 
by display-id is not currently pasted and the virtual display specified by 
top-display-id is pasted. 


DESCRIPTION SMG$MOVE_VIRTUAL—DISPLAY moves a pasted virtual display from its 

current position to the specified position and preserves the pasting order. If 
the display being moved is not currently pasted, SMG$MOVE—VIRTUAL _ 
DISPLAY presents the user with 2 options. By default, SMG$MOVE_ 
VIRTUAL—DISPLAY will paste the display at the top of the pasting order in 
the position specified. 

If, however, the optional argument top-display-id is specified, SMG$MOVE_ 
VIRTUAL—DISPLAY pastes the virtual display being moved under the virtual 
display specified by top-display-id. In this case, the virtual display specified 
by top-display-id must already be pasted. 

Note that a display cannot be moved from one pasteboard to another. 
However, the pasteboard-id is required because a given virtual display may 
be pasted to any number of pasteboards. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_INVDIS_ID 

SMG$_INVPAS_ID 

SMG$_WRONUMARG 

SMG$_ILLBATFNC 


Normal successful completion. 

Invalid display-id. 

Invalid pasteboard-id. 

Wrong number of arguments. 

Display is being batched; illegal operation. 


EXAMPLE 


Refer to the FORTRAN example shown in the SMG$REPASTE-VIRTUAL- 
DISPLAY routine. 
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SMG$PASTE_VIRTUAI_DISPLAY 

Paste Virtual Display 



SMG$PASTE_VIRTUAI_DISPLAY pastes a virtual display to a 

pasteboard. 

FORMAT 

SMG$PASTE_VIRTUAI_DISPLAY 

display-id f pasteboard-id 
,pasteboard-row 
, pasteboard-column 
[, top-display-id] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display to be pasted. The display-id argument is the 
address of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE-VIRTUAL-DISPLAY. 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard to which the display is to be pasted. The 
pasteboard-id argument is the address of an unsigned longword that contains 
the pasteboard identifier. 

pasteboard-row 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the row of the pasteboard that is to contain row 1 of the specified 
virtual display. The pasteboard-row argument is the address of a signed 
longword integer that contains the row number. 
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pasteboard-column 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column of the pasteboard that is to contain column 1 of the 
specified virtual display. The pasteboard-column argument is the address of 
a signed longword integer that contains the column number. 

top-display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Identifier of the virtual display under which to paste display-id. The optional 
top-display-id argument is the address of an unsigned longword containing 
this identifier. Note that the virtual display specified by top-display-id must 
already be pasted. 


DESCRIPTION SMG$PASTE .-VIRTUAL —DISPLAY places a display on a pasteboard and 

makes the display visible. If, however, the optional argument top-display-id 
is specified, SMG$PASTE—VIRTUAL—DISPLAY pastes the virtual display 
being pasted under the virtual display specified by top-display-id. In this 
case, the virtual display specified by top-display-id must already be pasted. 


CONDITION 

VALUES 

RETURNED 


EXAMPLE 


SSS—NORMAL 
SMG$_INVDIS_ID 
SMG$_INVPAS_ID 
SMG$_WRONUMARG 
SMG$_ILLBATFNC 


Normal successful completion. 

Invalid display-id. 

Invalid pasteboard-id. 

Wrong number of arguments. 

Display is being batched; illegal operation. 


0I1I2I3I4I6I6I7I 
12345678901234567890123456789012345678901234507890123456789012345678901234567890 
C CREPAS EATEN’SMG$CREATE_PASTEB0ARD' 

C CREDIS EXTON•SMG$CREATE_VIRTUAL_DISPLAY 1 

C PUTCHA EXTON' SMG$PUT_ CHARS 1 

C PASDIS EXTON' SMG$PASTE_VIRTUAL_DISPLAY' 


c 


Z-ADD0 

ZERO 

90 


c 


Z-ADD1 

LINCOL 

90 


c 


Z-ADD2 

LINE 

90 


c 


Z-ADD5 

COLUMN 

90 


c 


MOVE 'Menu' 

OUT 

4 


c* 

Create 

the pasteboard. 




c 


CALL CREPAS 




c 


PARM 

PASTID 

90 

WL 

c 


PARMV 

ZERO 



c 


PARM 

HEIGHT 

90 

WL 

c 


PARM 

WIDTH 

90 

WL 

c* 

Create 

the virtual display. 




c 


CALL CREDIS 




c 


PARM 

HEIGHT 


RL 

c 


PARM 

WIDTH 


RL 
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c 

PARM 

DISPID 

90 WL 

c* 

Output the 'Menu'. 



c 

CALL PUTCHA 



c 

PARM 

DISPID 

RL 

c 

PARMD 

OUT 


c 

PARM 

LINE 

RL 

c 

PARM 

COLUMN 

RL 

c* 

Paste the virtual display. 



c 

CALL PASDIS 



c 

PARM 

DISPID 

RL 

c 

PARM 

PASTID 

RL 

c 

PARM 

LINCOL 

RL 

c 

PARM 

LINCOL 

RL 

c 

SETON 


LR 


The RPG II program above displays 'Menu' beginning at line 2 column 5. 


This RPG II program calls several SMG$ routines. For another example of 
how to call SMG$PASTE-VIRTUAL-DISPLAY, see the RPG II example in 
the description of SMG$CREATE_PASTEBOARD. 
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direction 


VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the scrolling direction. The direction argument is the address of a 
longword that contains the direction code. Valid values are SMG$M_UP and 
SMG$M_DOWN. SMG$M_UP is the default. 


rendition-set 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Mask which denotes video attributes for the drawn line. The rendition-set 


argument is the address of an unsigned longword that contains a video 
attributes mask. Each bit attribute in this argument causes the corresponding 
attribute to be set in the display. 


Video attributes which can be manipulated in this manner are as follows: 


SMG$M_BLINK 
SMG$M_BOLD 
SMG$M_RE VERSE 

SMG$M_UNDERLINE 


Displays blinking characters 

Displays characters in higher-than-normal intensity 

Displays characters in reverse video, that is, using 
the opposite default rendition of the virtual display 

Displays underlined characters 


If the same bit is set in both the rendition-set and rendition-complement 
arguments, the Screen Management Facility applies the rendition-set 
attribute followed by the rendition-complement attribute. Using these two 
arguments, the caller can exercise independent control over each attribute in 
a single call. 


rendition-complement 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Mask which denotes video attributes for the line drawn. The rendition- 
complement argument is the address of an unsigned longword that contains 
a video attributes mask. 


Each bit attribute in this argument causes the corresponding attribute to be 
set in the display. Video attributes which can be manipulated in this manner 
are the same as for the rendition-set argument. 

The following table shows the action taken by the Screen Management 
Facility for various combinations of rendition-set and rendition-complement 
attributes. 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


Set 

Complement 

Action 

0 

0 

Attribute unchanged 

1 

0 

Attribute on 

0 

1 

Attribute set to complement of default setting 

1 

1 

Attribute off 


wrap-flag 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the action to take if the text does not fit on the line. The wrap-flag 
argument is the address of an unsigned longword that contains the flag. 0 
specifies no wrap (the default) while 1 specifies wrap. 


char-set 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the default character set for all text in this virtual display. The 
char-set argument is the address of a longword that contains the character set 
code. At this time, the only valid value is SMG$C_ASCII, which is also the 
default. 


SMG$INSERT_LINE lets you insert a line into a virtual display at a location 
other than the first or last line. Existing lines are scrolled in the specified 
direction to create an open space. If you specify a string argument, that string 
is written in the space created; otherwise, the new line remains blank. If the 
string does not span the width of the display, it is padded with blanks. 

If wrap-flag is set to 1 and the specified string is longer than the width of 
the virtual display, SMG$INSERT_LINE scrolls another line and writes the 
excess characters in the created space. If wrap-flag is 0, any excess characters 
are discarded. The virtual cursor remains at the character position following 
the last character written. 

See SMG$PUT_WITH_SCROLL to add lines and scroll at the first or last line 
in a virtual display. 


SS$_NORMAL 

SMG$_INVDIS_ID 

SMG$_WRONUMARG 

SMGS—INVROW 

SMG$_INVCOL 

SMG$_INVARG 


Normal successful completion. 

Invalid display-id. 

Wrong number of arguments. 

Invalid row. 

Invalid column. 

Invalid argument. The specified direction is not up 
or down. 


RTL-646 















Run-Time Library Routines 

SMG$INSERT_LINE 


EXAMPLE 


C+ 

C This FORTRAN example program demonstrates the use of SMG$INSERT_LINE. 

C 

C Include the SMG definitions. In particular, we want SMG$M_BORDER, 

C SMG$M_UNDERLINE, and SMG$M_UP. 

C- 

INCLUDE '(SSMGDEF)' 

INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD 
INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$PUT_CHARS, 

1 SMG$ERASE_DISPLAY 

INTEGER DISPLAY1, PASTE1, ROWS, COLUMNS 

C+ 

C Use SMG$CREATE_VIRTUAL_DISPLAY to create a virtual display 
C with a border. 

C- 

ROWS = 7 
COLUMNS = 50 

ISTATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS, COLUMNS. DISPLAY1, SMG$M_BORDER) 

IF (.NOT. ISTATUS) WRITE (6, 900) 'SMG$CREATE__VIRTUAL_DISPLAY', 

1 ISTATUS 

C+ 

C Call SMG$CREATE_PASTEBOARD to create the pasteboard. 

C- 

ISTATUS = SMG$CREATE_PASTEBOARD (PASTED 

IF (.NOT. ISTATUS) WRITE (6, 900) 'SMG$CREATE_PASTEBOARD', 

ISTATUS 

C+ 

C Use SMG$PUT_CHARS to put data in the virtual display. 

C- 

DISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This virtual display has 7 rows and 50 columns.’, 2, 1) 

ISTATUS = SMG$PUT_CHARS ( DISPLAYi, 

1 ' This is a bordered virtual display.', 4, 1) 

ISTATUS = SMG$PUT_CHARS ( DISPLAYI, 

1 ' SMG$PUT_CHARS puts data in this virtual display.', 6, 

1 1) 

C+ 

C Paste the virtual display by calling SMG$PASTE_VIRTUAL_DISPLAY. 

C- 

ISTATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAYI, PASTE1, 4, 15) 

900 FORMAT (' Routine ', A, ' returned a status of ', Z8) 

C+ 

C Call SMG$INSERT_LINE to add a line of text after line 6 and scroll 
C the display. Also, underline the new characters. 

C- 

ISTATUS = SMG$INSERT._LINE ( DISPLAYI, 7. 

1 'This is a new line.', SMG$M_UP, SMG$M_UNDERLINE) 

END 


The initial output generated by this FORTRAN program is shown in 
Figure RTL-25. 


RTL-647 







Run-Time Library Routines 

SMG$INSERT_LINE 


Figure RTL—25 


Output Generated Before the Call to 
SMG$INSERT_LINE 



ZK-4132-85 


The output generated after the call to SMG$INSERT_LINE is shown in 
Figure RTL-26. 

Figure RTL-26 Output Generated After the Call to 
SMG$IIMSERT_LIIME 
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SMG$INVALIDATE_DISPLAY—Mark a 

Display As 
Invalid 



SMG$INVALIDATE_DISPLAY marks a display as invalid and causes 
the entire display to be redrawn. 

FORMAT 

SMG$INVALIDATE-DISPLAY display-id 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display affected. The display-id argument is the address 
of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY. 


DESCRIPTION SMG$INVALIDATE_DISPLAY marks a display as invalid, and redraws the 



entire display. You would normally use this routine after you determine 
that output has been written to the display without benefit of the Screen 
Management Facility. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_INVDIS_ID Invalid display-id. 
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SMG$LABEI_BORDER—Label A Virtual 



Display Border 

SMG$LABEI_BORDER supplies a label for a virtual display's border. 

FORMAT 

SMG$LABEI_BORDER display-id[,label-text] 

[, position] [, units] 

[, renditionset] 

[, rendition-complement] 

[, char-set] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display affected. The display-id argument is the address 
of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE_VIRTUAL-DISPLAY. 

label-text 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

The new label for this display's border. The label-text argument is the 
address of a descriptor pointing to the label text. If omitted, the display 
becomes unlabeled. 

position 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies which of the display's borders contains the label. The position 
argument is the address of an unsigned longword that contains the position 
code. 

Valid positions are as follows: 

• SMG$K—TOP 

• SMG$K—BOTTOM 
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• SMG$K_RIGHT 

• SMG$K_LEFT 

If this argument is omitted, the label is displayed on the top border. 


units 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the character position at which the label begins within the border. 
The units argument is the address of a signed longword integer that contains 
the character position. If omitted, the label is centered in the specified border. 


rendition-set 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Mask which denotes video attributes for the drawn line. The rendition-set 
argument is the address of an unsigned longword that contains a video 
attributes mask. Each bit attribute in this argument causes the corresponding 
attribute to be set in the display. 


Video attributes which can be manipulated in this manner are as follows: 


SMG$M_BLINK 
SMG$M_BOLD 
SMG$M_RE VERSE 

SMG$M_UNDERLINE 


Displays blinking characters 

Displays characters in higher-than-normal intensity 

Displays characters in reverse video, that is, using 
the opposite default rendition of the virtual display 

Displays underlined characters 


If the same bit is set in both the rendition-set and rendition-complement 
arguments, the Screen Management Facility applies the rendition-set 
attribute followed by the rendition-complement attribute. Using these two 
arguments, the caller can exercise independent control over each attribute in 
a single call. 


rendition-complement 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


A mask which denotes video attributes for the line drawn. The rendition- 
complement argument is the address of an unsigned longword that contains 
a video attributes mask. Each bit attribute in this argument causes the 
corresponding attribute to be set in the display. Video attributes which can 
be manipulated in this manner are the same as those for the rendition-set 


argument. 


The following table shows the action taken by the Screen Management 
Facility for various combinations of rendition-set and rendition-complement 
attributes. 
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Set 

Complement 

Action 

0 

0 

Attribute unchanged 

1 

0 

Attribute on 

0 

1 

Attribute set to complement of default setting 

1 

1 

Attribute off 


char-set 


VMS Usage: longworcL-unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the default character set for all text in this virtual 
char-set argument is the address of an unsigned longword 
the character set code. At this time, the only valid value is 
which is also the default. 


display. The 
that contains 
SMG$C_ASCII, 


DESCRIPTION SMG$LABEL_BORDER lets you specify text to label a virtual display. If the 

specified virtual display does not already have the border display attribute 
(SMG$M_BORDER), then this attribute is forced. If the label string is 
supplied, it replaces the current label text for this border. If you supply an 
empty (null) label string, the border becomes unlabeled. If the label text 
(as positioned within the border) does not fit within the border, this routine 
returns SMG$_INVARG. 

Position and units together specify the starting position of the label text 
within a border. If position is omitted, the default is the top border. If units 
is omitted, this routine chooses a starting position so as to center the text 
either horizontally or vertically, depending on the implicit or explicit position 
argument. If both position and units are omitted, the text is centered in the 
top border. 

Units specifies the label's starting row or column position in the border. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_INVDIS_ID 

SMG$_INVARG 

SMG$_WRONUMARG 


Normal successful completion. 

Invalid display-id. 

Invalid argument. The combination of position, 
units, and label-text arguments resulted in a 
position outside the border area. 

Wrong number of arguments. 


EXAMPLE 


C+ 

C This FORTRAN example program demonstrates the use of SMG$LABEL_BORDER. 

C- 

C+ 

C Include the SMG definitions. In particular, we want SMG$M_BORDER, 

C SMG$K_TOP, SMG$K_BOTTOM, and SMG$K_RIGHT. 

C- 

INCLUDE 1 ($SMGDEF) 1 

INTEGER SMG$CREATE_VIRTUAL_DISPLAY. SMG$CREATE_PASTEBOARD 
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INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$PUT_CHARS 

INTEGER DISPLAY1, PASTE1 

INTEGER DISPLAY2, PASTE2 

INTEGER DISPLAY3, PASTE3, ROWS, COLUMNS 


C+ 

C Call SMG$CREATE_VIRTUAL_DISPLAY to create virtual display number 1. 

C Give it a border. 

C- 

ROWS = 4 
COLUMNS = 30 

ISTATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER) 

C+ 

C Call SMG$CREATE_VIRTUAL_DISPLAY to create virtual display number 2. 

C Give it a border. 

C- 

ROWS = 3 
COLUMNS = 30 

ISTATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS, COLUMNS, DISPLAY2, SMG$M_BORDER) 

C+ 

C Create virtual display number 3. Do NOT give it a border. 

C- 

ROWS = 4 
COLUMNS = 35 

ISTATUS = SMGlCREATE.VIRTUAL.DISPLAY 
1 (ROWS, COLUMNS, DISPLAY3) 

C+ 

C Use SMG$CREATE_PASTEBOARD to create the pasteboard. 

C- 

ISTATUS = SMG$CREATE_PASTEBOARD (PASTED 
C+ 

C Call SMGlPUT.CHARS to put data into the virtual displays. 

C- 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' A bordered virtual display.', 2, 1) 

ISTATUS = SMGlPUT.CHARS ( DISPLAY2, 

1 ' A bordered virtual display.', 1, 1) 

ISTATUS * SMGIPUT.CHARS ( DISPLAY3, 

1 ' Started as am unbordered display.', 2, 1) 

C+ 

C Call SMGILABEL.BORDER to label the virtual display borders. 

C- 

ISTATUS = SMGILABEL.BORDER ( DISPLAY1, 'Side', SMGlK.RIGHT) 
ISTATUS = SMGILABEL.BORDER ( DISPLAY2, 'LABEL Bottom'. 

1 SMGIK.BOTTOM, 1) 

ISTATUS = SMGILABEL.BORDER ( DISPLAY3, 'Forced bordering ', 

1 SMGIK.TOP) 

C+ 

C Call SMGIPASTE.VIRTUAL.DISPLAY to paste the virtual displays. 

C- 

ISTATUS = SMGIPASTE.VIRTUAL.DISPLAY ( DISPLAY1, PASTE1, 2, 10) 

ISTATUS = SMGIPASTE.VIRTUAL.DISPLAY ( DISPLAY2, PASTE1, 2. 45) 

ISTATUS = SMGIPASTE.VIRTUAL.DISPLAY ( DISPLAY3, PASTE1, 10. 5) 

900 FORMAT (' Routine '.A, ' returned a status of ', Z8) 

END 


The output generated by this program is shown in Figure RTL-27. 
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Figure RTL-27 


Output Generated by Program Calling 
SMG$LABEI—BORDER 
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SMG$LIST_KEY_DEFS—List Key 

Definitions 



SMG$LIST_KEY_DEFS returns the definition (equivalence string) 
associated with a specified key in a specified key table. 

FORMAT 

SMG$LIST_KEY_DEFS key-table-id,context 

[, key-name] [, if-state] 

[,attributes] [,equiv-string] 

[,state-string] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

key-table-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read-only 

mechanism: by reference 

Specifies the key table from which you are extracting a key definition. The 
key-table-id argument is the address of an unsigned longword that contains 
the key table identifier. 

Key-table-id is returned by the SMG$CREATE_KEY_TABLE routine. 

context 

VMS Usage: context 
type: longword integer (signed) 

access: modify 

mechanism: by reference 

Provides a means to extract a series of key definitions from a key table. The 
context argument is the address of a signed longword integer that contains 
the context variable. For the first call to this routine, you should set the 
context argument to zero. 

Context is incremented by the SMG$LIST_KEY_DEFS routine so that the 
next call returns the next key definition. 

key-name 

VMS Usage: char_string 
type: character string 

access: modify 

mechanism: by descriptor 

Identifies the key whose value you are listing. The key-name argument is 
the address of a descriptor pointing to the key name. 
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if-state 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Receives the state name which qualifies the next definition in the key table. 
The if-state argument is the address of a descriptor pointing to the storage 
into which the state name is written. 


attributes 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Attributes of this key definition. The attributes argument is the address of an 
unsigned longword into which is written the key attributes. 


Possible attributes are as follows: 


SMG$V_KEY_NOECHO (Bit 0) 


SMG$V_KEY_TERMINATE (Bit 1) 


SMG$V_KEY_LOCKSTATE (Bit 2) 


SMG$V_KEY_PROTECTED (Bit 3) 


If set, this bit specifies that equiv_ f 
string is not to be echoed when 
this key is pressed; if clear, equiv_ 
string is echoed. If SMG$V_KEY_ 
TERMINATE is not set, SMG$V_ 
KEY_NOECHO is ignored. 

If set, this bit specifies that when 
this key is pressed (as qualified by 
if-state), the input line is complete 
and more characters should not be 
accepted. If clear, more characters 
may be accepted. 

If set, and if state-string is specified, 
the state name specified by state¬ 
string remains the current state until 
explicitly changed by a subsequent 
keystroke whose definition includes a 
state-string. If clear, the state name 
specified by state-string remains in 
effect only for the next defined key 
stroke. 

If set, this bit specifies that this key 
definition cannot be modified or 
deleted. If clear, the key definition 
can be modified or deleted. 


The remaining bits are undefined. 


equiv-string 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

The character string into which is written the equivalence string for the next 
key definition. The equiv-string argument is the address of a descriptor 
pointing to the storage into which the equivalence string is written. 
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state-string 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

A string into which is written the new state name, if any, which is set by the 
next key definition. The state-string argument is the address of a descriptor 
pointing to the storage into which the state name is written. If this key 
definition sets a state, the attributes flag SMG$V_KEY_SETSTATE is set. 

DESCRIPTION 

SMG$LIST_KEY_DEFS, when called repeatedly, lets you examine all the 
definitions in a key table. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_INVKTB_ID Invalid key-table-id. 

SMG$_NOMOREKEYS No more keys in this table. 

Any condition value returned by LIB$COPY_DXDX. 
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SMG$LOAD_KEY_DEFS—Load Key 

Definitions 



SMG$LOAD_KEY_DEFS loads a file of key definitions (DEFINE/KEY 
commands) into a specified key table. 

FORMAT 

SMG$LOAD_KEY_DEFS key-table-id,filespec 

[, default-filespec] 
[,lognam-flag] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

key-table-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the key table into which you are loading key definitions. The 
key-table-id argument is the address of an unsigned longword that contains 
the key table identifier. 

Key-table-id is returned by SMG$CREATE—KEY__TABLE. 

filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String containing the file specification for the file of DEFINE/KEY commands. 
The filespec argument is the address of a descriptor pointing to the file 
specification. 

default-filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String containing the default file specification for the file of DEFINE/KEY 
commands. The default-filespec argument is the address of a descriptor 
pointing to the default file specification. If omitted, the null string is used. 
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lognam-flag 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies whether filespec is to be treated as a logical name. The lognam-flag 
argument is the address of an unsigned longword that contains the flag. If 
set, lognam-flag specifies that filespec should be translated, but if this is not 
possible, that the null string be used. 

DESCRIPTION 

SMG$LOAD_KEY_DEFS opens and reads a file containing DEFINE/KEY 
commands and calls SMG$DEFINE_KEY for each command line in the file. 
Use of SMG$LOAD_KEY_DEFS requires that the calling program be run 
under the DCL command language interpreter. This routine signals any 
errors encountered while processing command lines. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_FILTOOLON File specification is too long (over 255 characters). 

Any condition values returned by SMG$DEFINE_KEY. 

Any condition values returned by $OPEN. 
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SMG$MOVE—VIRTU Al_DISPLAY—Move 

Virtual 



Display 

SNG$MOVE_VIRTUAl_DISPLAY relocates a virtual display on a 

pasteboard and preserves the pasting order. 

FORMAT 

SMG$MOVE_VIRTUAI—DISPLAY 

display-id ,pasteboard-id 
,pasteboard-row 
„ pasteboard-column 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display to be moved. The display-id argument is the 
address of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE_VIRTUAL-DISPLAY. 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard on which the movement is to take place. The 
pasteboard-id argument is the address of an unsigned longword that contains 
the pasteboard identifier. 

Pasteboard-id is returned by SMG$CREATE—PASTEBOARD. 

pasteboard-row 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the row of the pasteboard which is to contain row 1 of the specified 
virtual display. The pasteboard-row argument is the address of a signed 
longword integer that contains the row number. 
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pasteboard-column 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column of the pasteboard which is to contain column 1 of the 
specified virtual display. The pasteboard-column argument is the address of 
a signed longword integer that contains the column number. 


DESCRIPTION SMG$MOVE_VIRTUAL_DISPLAY moves a virtual display from its current 

position to the specified position, and preserves the pasting order. If the 
display is not currently pasted, SMG$MOVE_VIRTUAL_DISPLAY pastes the 
display at the top of the pasting order in the position specified. 

Note that a display cannot be moved from one pasteboard to another. 
However, the pasteboard-id is required because a given virtual display may 
be pasted to any number of pasteboards. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_INVDIS_ID 

SMG$_INVPAS_ID 

SMG$_WRONUMARG 


Normal successful completion. 
Invalid display-id. 

Invalid pasteboard-id. 

Wrong number of arguments. 


EXAMPLE 


Refer to the FORTRAN example shown in the SMG$REPASTE_VIRTUAL- 
DISPLAY routine. 
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SMG$PASTE—VIRTUAI_DISPLAY 

Paste Virtual Display 

SMG$PASTE_VIRTUAI_DISPLAY pastes a virtual display to a 



pasteboard. 

FORMAT 

SMG$PASTE_VIRTUAI_DISPLAY 

display-id ,pasteboard-id 
, pasteboard-row 
,pasteboard-column 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display to be pasted. The display-id argument is the 
address of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY. 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard to which the display is to be pasted. The 
pasteboard-id argument is the address of an unsigned longword that 
contains the pasteboard identifier. 

pasteboard-row 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the row of the pasteboard which is to contain row 1 of the specified 
virtual display. The pasteboard-row argument is the address of a signed 
longword integer that contains the row number. 
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pasteboard-column 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column of the pasteboard which is to contain column 1 of the 
specified virtual display. The pasteboard-column argument is the address of 
a signed longword integer that contains the column number. 


DESCRIPTION 

SMG$PASTE_VIRTUAL_DISPLAY places a display on a pasteboard and 
makes the display visible. 

CONDITION 

SS$_NORMAL 

Normal successful completion. 

VALUES 

SMG$_INVDIS_ID. 

Invalid display-id. 

RETURNED 

SMG$_INVPAS_ID 

Invalid pasteboard-id. 


SMG$_WRONUMARG 

Wrong number of arguments. 


EXAMPLE 


0I1I2I3I4I5I6I7I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 
C CREPAS EXTRN'SMG$CREATE_PASTEBOARD' 

C CREDIS EXTRN'SMG$CREATE_VIRTUAL_DISPLAY' 

C PUTCHA EXTRN'SMG$PUT_CHARS' 

C PASDIS EXTRN'SMG$PASTE_VIRTUAL_DISPLAY' 


c 

Z-ADDO 

ZERO 

90 


c 

Z-ADD1 

LINCOL 

90 


c 

Z-ADD2 

LINE 

90 


c 

Z-ADD5 

COLUMN 

90 


c 

MOVE 'Menu' 

OUT 

4 


c* 

Create the pasteboard. 




c 

CALL CREPAS 




c 

PARM 

PASTID 

90 

WL 

c 

PARMV 

ZERO 



c 

PARM 

HEIGHT 

90 

WL 

c 

PARM 

WIDTH 

90 

WL 

c* 

Create the virtual display. 




c 

CALL CREDIS 




c 

PARM 

HEIGHT 


RL 

c 

PARM 

WIDTH 


RL 

c 

PARM 

DISPID 

90 

WL 

c* 

Output the 'Menu'. 




c 

CALL PUTCHA 




c 

PARM 

DISPID 


RL 

c 

PARMD 

OUT 



c 

PARM 

LINE 


RL 

c 

PARM 

COLUMN 


RL 

c* 

Paste the virtual display. 




c 

CALL PASDIS 




c 

PARM 

DISPID 


RL 

c 

PARM 

PASTID 


RL 

c 

PARM 

LINCOL 


RL 

c 

PARM 

LINCOL 


RL 

c 

SETON 



LR 


The RPG II program above displays 'Menu' beginning at line 2 column 5. 
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This RPG II program calls several SMG$ routines. For another example of 
how to call SMG$PASTE__VIRTUAL_DISPLAY, see the RPG II example in 
the description of SMG$CREATE_PASTEBOARD. 
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SMG$POP_VIRTUAI_DISPLAY—Delete a 

Series of Virtual Displays 

SMG$POP_VIRTUAI—DISPLAY deletes a specified virtual display 



and all displays that were pasted on the specified pasteboard after 
the specified virtual display. 

FORMAT 

SMG$POP_VIRTUAI_DISPLAY 

display-id ,pasteboard-id 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the lowest (first) virtual display to be deleted. The display-id 
argument is the address of an unsigned longword that contains the display 
identifier. All displays that are higher in the pasting order (that is, all displays 
that were pasted after the specified display) are deleted as well. 

Display-id is returned by SMG$CREATE—VIRTUAL—DISPLAY. 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard on which the display deletions take place. The 
pasteboard-id argument is the address of an unsigned longword that contains 
the pasteboard identifier. 

DESCRIPTION 

SMG$POP—VIRTUAL—DISPLAY deletes (not merely unpastes) one or more 
displays from the specified pasteboard, starting with the display specified and 
including all displays that are higher in the pasting order (that is, all displays 
that were pasted after the specified display). 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_INVDIS_ID 

SMG$_INVPAS_ID 

SMG$_WRONUMARG 


Normal successful completion. 
Invalid display-id. 

Invalid pasteboard-id. 

Wrong number of arguments. 
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SMG$PUT_CHARS—Write Characters to 

a Virtual Display 

SMG$PUT_CHARS overwrites characters in a virtual display with 
the text you specify. 


FORMAT SMG$PUT_CHARS display-id,text[,line-number] 

[, column-number] 

[, erase-flag] [, rendition-set] 

[, rendition-complement] 

[, char-set] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by value 


ARGUMENTS display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display affected. The display-id argument is the address 
of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY. 


text 

VMS Usage: char—string 
type: character string 

access: read only 

mechanism: by descriptor 

Characters to be written to the virtual display. The text argument is the 
address of a descriptor pointing to the character string. 


line-number 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the line at which output begins. If line-number is omitted, output 
begins on the current line. The line-number argument is the address of a 
signed longword integer that contains the line number. 
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column-number 


VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column at which output begins. If column-number is omitted, 
output begins on the current column. The column-number argument is the 
address of a signed longword integer that contains the column number. 


erase-flag 


VMS Usage: 
type: 
access: 
mechanism: 


mask_longword 
longword (unsigned) 
read only 
by reference 


Specifies whether to erase the line before writing the specified text. The 
erase-flag argument is the address of an unsigned longword that contains the 
flag. If set, the line will be erased. The default is not to erase. 


rendition-set 


VMS Usage: 
type: 
access: 
mechanism: 


mask_longword 
longword (unsigned) 
read only 
by reference 


Mask which denotes video attributes for the drawn line. The rendition-set 


argument is the address of an unsigned longword that contains a video 
attributes mask. Each bit attribute in this argument causes the corresponding 
attribute to be set in the display. 


Video attributes which can be manipulated in this manner are as follows: 


SMG$M_BLINK 

SMG$M_BOLD 

SMG$M_REVERSE 

SMG$M_UNDERLINE 


Displays blinking characters 

Displays characters in higher-than-normal intensity 

Displays characters in reverse video, that is, using 
the opposite default rendition of the virtual display 

Displays underlined characters 


If the same bit is set in both the rendition-set and rendition-complement 
arguments, the Screen Management Facility applies the rendition-set 
attribute followed by the rendition-complement attribute. Using these two 
arguments, the caller can exercise independent control over each attribute in 
a single call. 


rendition-complement 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Mask which denotes video attributes for the line drawn. The rendition- 
complement argument is the address of an unsigned longword that contains 
a video attributes mask. 


Each bit attribute in this argument causes the corresponding attribute to be 
set in the display. Video attributes which can be manipulated in this manner 
are the same as those for the rendition-set argument. 
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The following table shows the action taken by the Screen Management 
Facility for various combinations of rendition-set and rendition-complement 
attributes. 


Set 

Complement 

Action 

0 

0 

Attribute unchanged 

1 

0 

Attribute on 

0 

1 

Attribute set to complement of default setting 

1 

1 

Attribute off 


char-set 


VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the default character set for all text in this virtual 
char-set argument is the address of an unsigned longword 
the character set code. At this time, the only valid value is 
which is also the default. 


display. The 
that contains 
SMG$C_ASCII, 


DESCRIPTION 

SMG$PUT_CHARS writes text to the specified virtual display, overwriting 
any existing text. (See SMG$INSERT_CHARS to write new text while 
preserving existing text.) 

By default, SMG$PUT_CHARS modifies only those character positions where 
new text is written. However, the caller can erase the line before the new 
text is written by setting the erase-flag argument. The cursor remains at the 
character position immediately following the last text written. Note that this 
routine writes to a single line; excess characters at the end of the line are 
discarded. 

CONDITION 

SS$_NORMAL 

Normal successful completion. 

VALUES 

SMG$_INVCOL 

Invalid column. 

RETURNED 

SMG$_INVROW 

Invalid row. 


SMG$_WRONUMARG 

Wrong number of arguments. 


SMG$_INVDIS_ID 

Invalid display-id. 


LIB$_INVSTRDES 

Invalid string descriptor. 


EXAMPLES 


n o 

C This FORTRAN example program demonstrates the use of 
C SMG$PUT_CHARS. 

C- 


INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD 
INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$PUT_CHARS 
INTEGER DISPLAY1, PASTE1, ROWS. COLUMNS. BORDER 
C+ 

C Create the virtual display. To give it a border, set BORDER = 1. 
C No border would be BORDER = 0. 

C- 
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C+ 


ROWS = 7 
COLUMNS * 50 
BORDER = 1 

ISTATUS = SMG$CREATE_VIRTUAL_DISPLAY 

(ROWS, COLUMNS, DISPLAY1, BORDER) 

IF (.NOT. ISTATUS) WRITE (6, 900) 'SMG$CREATE_VIRTUAL_DISPLAY', ISTATUS 


C Create the pasteboard. 
C- 


ISTATUS = SMG$CREATE_PASTEBOARD (PASTED 

IF (.NOT. ISTATUS) WRITE (6, 900) 'SMG$CREATE_PASTEBOARD', ISTATUS 


C+ 

C Put data in the virtual display. 
C- 


ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This virtual display has 7 

ISTATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This is a bordered virtual 

ISTATUS = SMG$PUT_CHARS ( DISPLAYl, 

1 ' SMG$PUT_CHARS puts data in 

C+ 

C Paste the virtual display. 

C- 


rows and 50 columns.', 2, 1) 

display.', 4, 1) 

this virtual display.', 6, 1) 


ISTATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAYl, PASTE1, 4, 15) 

900 FORMAT (' Routine ', A, ' returned a status of ', Z8) 

END 


The output generated by this FORTRAN program is shown in Figure RTL-28. 

Figure RTL-28 Output of FORTRAN Program Calling 

SMG$PUT_CHARS 



ZK-4116-85 


For an example of how to call SMG$PUT_CHARS, see the RPG II example 
provided in the description of SMG$CREATE_PASTEBOARD. 
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SMG$PUT_CHARS_HIGHWIDE—Write 
Double-Height Double-Width Characters 

SMG$PUT_CHARS_HIGHWIDE writes double-height, double-width 



characters to a virtual display. 

FORMAT 

SMG$PUT_CHARS_HIGHWIDE 

display-id , text [Jine-number] 

[, column-number] [, rendition-set] 

[, rendition-complement] ], char-set] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display affected. The display-id argument is the address 
of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE—VIRTUAL—DISPLAY. 

text 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Characters to be written to the virtual display. The text argument is the 
address of a descriptor pointing to the text. 

line-number 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the line at which output begins. The line-number argument is 
the address of a signed longword integer that contains the line number. If 
line-number is omitted or if it is equal to zero, output begins on the current 
line. 
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column-number 


VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column at which output begins. The column-number argument 
is the address of a signed longword integer that contains the column number. 
If column-number is omitted or if it is equal to zero, output begins on the 
current column. 


rendition-set 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Mask which denotes video attributes for the drawn line. The rendition-set 
argument is the address of an unsigned longword that contains a video 
attributes mask. Each bit attribute in this argument causes the corresponding 
attribute to be set in the display. 


Video attributes which can be manipulated in this manner are as follows: 


SMG$M_BLINK 
SMG$M_BOLD 
SMG$M_RE VERSE 

SMG$M_UNDERLINE 


Displays blinking characters 

Displays characters in higher-than-normal intensity 

Displays characters in reverse video, that is, using 
the opposite default rendition of the virtual display 

Displays underlined characters 


If the same bit is set in both the rendition-set and rendition-complement 
arguments, the Screen Management Facility applies the rendition-set 
attribute followed by the rendition-complement attribute. Using these two 
arguments, the caller can exercise independent control over each attribute in 
a single call. 


rendition-complement 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Mask which denotes video attributes for the line drawn. The rendition- 
complement argument is the address of an unsigned longword that contains 
a video attributes mask. 


Each bit attribute in this argument causes the corresponding attribute to be 
set in the display. Video attributes which can be manipulated in this manner 
are the same as those for the rendition-set argument. 

The following table shows the action taken by the Screen Management 
Facility for various combinations of rendition-set and rendition-complement 
attributes. 
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Set 

Complement 

Action 

0 

0 

Attribute unchanged 

1 

0 

Attribute on 

0 

1 

Attribute set to complement of default setting 

1 

1 

Attribute off 


char-set 


VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the default character set for all text in this virtual 
char-set argument is the address of an unsigned longword 
the character set code. At this time, the only valid value is 
which is also the default. 


display. The 
that contains 
SMG$C_ASCII, 


SMG$PUT_CHARS_HIGHWIDE writes double-height, double-width 
characters to the specified virtual display. The corresponding pasteboard line 
cannot contain a mixture of single-height/width and double-height/width 
characters; if the line contains single-height/width characters, the entire line 
is rewritten in double width and height. Otherwise, only the specified text 
is written. If the text does not span the line, it is padded with blanks. The 
virtual cursor remains at the character position immediately following the last 
text written. 

Note that if the terminal does not support double height characters, the same 
characters will be displayed on two successive lines. 


SSS—NORMAL 

SMG$_INVCOL 

SMG$_INVROW 

LIB$_INVSTRDES 

SMG$_WRONUMARG 

SMG$_INVDIS_ID 


Normal successful completion. 
Invalid column. 

Invalid row. 

Invalid string descriptor. 
Wrong number of arguments. 
Invalid display-id. 
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SMG$PUT_CHARS_WIDE—Write Wide 

Characters 



SMG$PUT_CHARS_WIDE writes double-width characters to a 
virtual display. 

FORMAT 

SMG$PUT_CHARS_WIDE 

display-id, text [Jine-number] 

[, column-number] [, rendition-set] 

[, rendition-complement] [, char-set] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display affected. The display-id argument is the address 
of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE—VIRTUAL—DISPLAY. 

text 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Characters to be written to the virtual display. The text argument is the 
address of a descriptor pointing to the text. 

line-number 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the line at which output begins. If line-number is omitted, output 
begins on the current line. The line-number argument is the address of a 
signed longword integer that contains the line number. 
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column-number 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column at which output begins. If column-number is omitted, 
output begins on the current column. The column-number argument is the 
address of a signed longword integer that contains the column number. 


rendition-set 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Mask which denotes video attributes for the drawn line. The rendition-set 
argument is the address of an unsigned longword that contains a video 
attributes mask. Each bit attribute in this argument causes the corresponding 
attribute to be set in the display. 


Video attributes which can be manipulated in this manner are as follows: 


SMG$M_BLINK 
SMG$M_BOLD 
SMG$M_RE VERSE 

SMG$M_UNDERLINE 


Displays blinking characters 

Displays characters in higher-than-normal intensity 

Displays characters in reverse video, that is, using 
the opposite default rendition of the virtual display 

Displays underlined characters 


If the same bit is set in both the rendition-set and rendition-complement 
arguments, the Screen Management Facility applies the rendition-set 
attribute followed by the rendition-complement attribute. Using these two 
arguments, the caller can exercise independent control over each attribute in 
a single call. 


rendition-complement 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Mask which denotes video attributes for the line drawn. The rendition- 
complement argument is the address of an unsigned longword that contains 
a video attributes mask. Each bit attribute in this argument causes the 
corresponding attribute to be set in the display. Video attributes which can 
be manipulated in this manner are the same as those for the rendition-set 


argument. 


The following table shows the action taken by the Screen Management 
Facility for various combinations of rendition-set and rendition-complement 
attributes. 


Set 

Complement 

Action 

0 

0 

Attribute unchanged 

1 

0 

Attribute on 

0 

1 

Attribute set to complement of default setting 

1 

1 

Attribute off 
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char-set 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the default character set for all text in this virtual display. The 
char-set argument is the address of an unsigned longword that contains 
the character set code. At this time, the only valid value is SMG$C_ASCII, 
which is also the default. 

DESCRIPTION 

SMG$PUT_CHARS_WIDE writes double-width text to the specified virtual 
display, overwriting any existing text. The line cannot contain a mixture 
of single- and double-width characters; if the line previously contained 
single-width characters, then the entire line will be rewritten. The virtual 
cursor is left at the first character position following the text written. 

CONDITION 

VALUES 

RETURNED 

SSS—NORMAL Normal successful completion. 

SMG$_INVCOL Invalid column. 

SMG$_INVROW Invalid row. 

SMG$_WRONUMARG Wrong number of arguments. 

SMG$_INVDIS_ID Invalid display-id. 

LIB$_INVSTRDES Invalid string descriptor. 
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SMG$PUT_LINE—Write Line to Virtual 

Display 

SMG$PUT_LINE writes a line of text to a virtual display. 


FORMAT SMG$PUT_LINE display-id,text 

[, line-advance] [, rendition-se t] 
[,rendition-complement] 

[, wrap-flag] [, char-set] [, direction] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


ARGUMENTS display-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display affected. The display-id argument is the address 
of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CRE ATE-VIRTUAL -DISPLAY. 


text 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

The characters to be written to the virtual display. The text argument is the 
address of a descriptor pointing to the text. 


line-advance 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the number of lines to advance after output. The line-advance 
argument is the address of a signed longword integer that contains the 
number of lines to advance. The default is 1. 
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rendition-set 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


A mask that denotes video attributes for the drawn line. The rendition- 
set argument is the address of an unsigned longword that contains a video 
attributes mask. Each bit attribute in this argument causes the corresponding 
attribute to be set in the display. 


Video attributes that can be manipulated in this manner are as follows: 


SMG$M _BLINK 
SMG$M_BOLD 
SMG$M_REVERSE 

SMG$M_UNDERLINE 


Displays blinking characters. 

Displays characters in higher-than-normal intensity. 

Displays characters in reverse video, that is, using 
the opposite default rendition of the virtual display. 

Displays underlined characters. 


If the same bit is set in both the rendition-set and rendition-complement 
arguments, the Screen Management Facility applies the rendition-set attribute 
followed by the rendition-complement attribute. Using these two arguments, 
the caller can exercise independent control over each attribute in a single call. 


rendition-complement 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

A mask that denotes video attributes for the line drawn. The rendition- 
complement argument is the address of an unsigned longword that contains 
a video attributes mask. Each bit attribute in this argument causes the 
corresponding attribute to be set in the display. Video attributes that can 
be manipulated in this manner are the same as those for the rendition-set 
argument. 


The following table shows the action taken by the Screen Management 
Facility for various combinations of rendition-set and rendition-complement 
attributes. 


Set 

Complement 

Action 

0 

0 

Attribute unchanged. 

1 

0 

Attribute on. 

0 

1 

Attribute set to complement of default setting. 

1 

1 

Attribute off. 


RTL-678 


April 1986 






Run-Time Library Routines 

SMG$PUT_LINE 


wrap-flag 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the action to take if the text does not fit on the line. The wrap-flag 
argument is the address of an unsigned longword that contains the flag. Zero 
specifies no wrap (the default) while 1 specifies wrap. 
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char-set 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the default character set for all text in this virtual display. The 
char-set argument is the address of an unsigned longword that contains 
the character set code. At this time, the only valid value is SMG$C_ASCII, 
which is also the default. 

direction 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the direction to scroll, if scrolling is necessary. The direction 
argument is the address of an unsigned longword that contains the direction 
code. Valid values are SMG$M_UP and SMG$M_DOWN. SMG$M_UP is 
the default. 

DESCRIPTION 

SMG$PUT_LINE writes lines of text to the virtual display, beginning at the 
current line. Once text reaches the bottom or top line (depending on the 
scrolling direction), subsequent calls to this routine cause the display to scroll. 
SMG$PUT_LINE writes out the entire line, starting at the current virtual 
cursor position. If the caller's text does not span the entire line, the line is 
padded with blanks. 

If wrap-flag is set, lines are scrolled line-advance times to make room for the 
overflow characters in the "next" line. The "next" line is determined by the 
scrolling direction. If wrap-flag is clear, excess characters are discarded. 

Following a call to SMG$PUT_LINE, the virtual cursor position is set to 
column 1 of the next line where output should occur. The next line where 
output should occur is determined by the line-advance argument; line- 
advance defaults to 1 so that subsequent calls to SMG$PUT_LINE will not 
cause overprinting. Other SMG$ procedures that can be used to write lines of 
text to a virtual display are SMG$PUT_LINE_WIDE and SMG$PUT_LINE_ 
HIGHWIDE. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_INVDIS_ID Invalid display-id. 

SMG$_WRONUMARG Wrong number of arguments. 

LIB$_INVSTRDES Invalid string descriptor. 


EXAMPLES 

D » 

C This FORTRAN example program demonstrates the use of SMG$PUT_LINE. 

C- 

C+ 

C Include the SMG definitions. In particular, we want SMG$M_BORDER and 
C SMG$M_UNDERLINE. 

C- 
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IMPLICIT INTEGER (A-Z) 
INCLUDE '(ISMGDEF)' 
CHARACTER*30 TEXT(3) 


C+ 

C Create a virtual display with a border. 

C- 

ROWS = 7 
COLUMNS = 50 

STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS, COLUMNS, DISPLAY1, SMG$M_B0RDER) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(7.VAL(STATUS)) 

C+ 

C Create the pasteboard. 

C- 

STATUS = SMG$CREATE_PASTEBOARD (PASTED 
IF (.NOT. STATUS) CALL LIB$SIGNAL(7.VAL(STATUS)) 

C+ 

C Put data in the virtual display. 

C- 

TEXT(l) - 'This virtual display has 7' 

TEXT(2) = 'rows and 50 columns.' 

TEXT(3) = 'Text entered by SMG$PUT_LINE.' 

C+ 

C After the first line of text is printed, call SMG$PUT_LINE to 
C advance two lines. 

C- 

STATUS = SMG$PUT_LINE ( DISPLAY1, TEXT(l), 2) 

IF (.NOT. STATUS) CALL LIB$SIGNAL C/.VAL (STATUS) ) 

C+ 

C Now, use SMG$PUT_LINE to underline the next line of text. 

C Notice that 30 characters are being underlined. Advance 1 
C line of text after displaying the line. 

C- 


STATUS * SMG$PUT_LINE ( DISPLAY1, TEXT(2), 1, SMG$M_UNDERLINE) 
IF (.NOT. STATUS) CALL LIB$SIGNAL C/.VAL (STATUS)) 

C+ 

C Display the third line of text. 

C- 


STATUS = SMG$PUT_LINE ( DISPLAY1, TEXT(3)) 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 


C+ 

C Paste the virtual display. 
C- 


STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1. 4, 15) 
IF (.NOT. STATUS) CALL LIB$SIGNAL C/.VAL (STATUS)) 

END 


The output generated by this FORTRAN program is shown in Figure RTL-29. 
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Figure RTL-29 


Output Generated by FORTRAN Program Calling 
SMG$PUT_LINE 



The following program illustrates the use of the new direction argument to 
SMG$PUT_LINE. This new capability has made the Screen Management 
Routine SMG$PUT_WITH-SCROLL obsolete. 


S 


c+ 

c 

c 

c 

c 

c 

c 

c 

c- 


This FORTRAN example program demonstrates the use of the DIRECTION 
parameter in the SMG$PUT_LINE routine. 

The DIRECTION parameter in SMG$PUT_LINE makes SMG$PUT_WITH_SCROLL 
an obsolete routine. This example is the same as the SMG$PUT_WITH_SCROLL, 
except that the calls to SMG$PUT_WITH_SCROLL have been replace by calls 
to SMGIPUT.LINE. 



PARAMETER 

PARAMETER 

PARAMETER 

PARAMETER 

PARAMETER 

PARAMETER 


SMG$M_UP = 1 
SMG$M_DOWN = 2 
SMG$M_B0LD = 1 
SMG$M_REVERSE = 2 
SMG$M_BLINK = 4 
SMG$M_UNDERLINE = 8 


IMPLICIT INTEGER*4 (A-Z) 


C+ 

C Call SMG$CREATE_PASTEBOARD to establish the terminal screen 
C as a pasteboard. 

C- 


STATUS = SMG$CREATE_PASTEBOARD (NEW.PID) 

IF (.NOT. STATUS) CALL LIB$ST0P(7.VAL(STATUS)) 


C Using SMG$CREATE_VIRTUAL_DISPLAY, establish a virtual display region. 
C- 

STATUS = SMG$CREATE_VIRTUAL_DISPLAY (5.80.DISPLAYED) 

IF (.NOT. STATUS) CALL LIB$ST0PC/.VAL(STATUS)) 



C+ 

C Paste the virtual display to the screen, starting at 
C row 10. column 15 by calling SMG$PASTE_VIRTUAL_DISPLAY. 
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c- 

STATUS = SMGIPASTE.VIRTUAL.DISPLAY(DISPLAY_ID,NEW_PID,10,15) 
IF (.NOT. STATUS) CALL LIB$ST0P(7.VAL(STATUS)) 

C+ 

C Define a scrolling region through a call to 
C SMG$SET_DISPLAY_SCROLL_REGION. 

C- 


STATUS = SMG$SET_DISPLAY_SCROLL_REGION(DISPLAY_ID,1,5) 

IF (.NOT. STATUS) CALL LIBlSTOP(7.VAL(STATUS)) 

C+ 

C Call SMGlPUT.LINE and SMG$ERASE_LINE to write three 
C scrolling lines to the screen. The first line will be underlined, 
C the second blinking, and the third in reverse video. 

C- 

DO I = 1,10 

IF (U/2) ♦ (1/2) .EQ. I) THEN 
DIR = SMG$M_UP 

ELSE 

DIR = SMG$M_D0WN 

ENDIF 

STATUS = SMG$PUT_LINE (DISPLAY.ID, 

1 'This line is underlined',,SMGlM.UNDERLINE,,,,DIR) 

IF (.NOT. STATUS) CALL LIBlSTOP (7.VAL (STATUS) ) 

STATUS = SMGIERASE.LINE(DISPLAY.ID) 

IF (.NOT. STATUS) CALL LIBlSTOP(7.VAL(STATUS)) 

STATUS « SMGlPUT.LINE (DISPLAYED, 'This line is blinking', , 

1 SMGIM.BLINK,,,,DIR) 

IF (.NOT. STATUS) CALL LIBlSTOP(7.VAL(STATUS)) 

STATUS = SMGIERASE.LINE (DISPLAY.ID) 

IF (.NOT. STATUS) CALL LIBlSTOP(7.VAL(STATUS)) 

STATUS = SMGIPUT.LINE (DISPLAY_ID,'This line is reverse 
1 video',,SMGIM.REVERSE,,,,DIR) 

IF (.NOT. STATUS) CALL LIBlSTOP(7.VAL(STATUS)) 

STATUS = SMGIERASE.LINE (DISPLAY.ID) 

IF (.NOT. STATUS) CALL LIBlSTOP(7.VAL(STATUS)) 

ENDDO 

END 
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SMG$PUT_LINE_HIGHWIDE 

Write Double High and Double Wide Line 



SMG$PUT_LINE_HIGHWIDE writes lines with double high and 
double wide characters. 

FORMAT 

SMG$PUT_LINE_HIGHWIDE 

display-id, text [, line-adv] 

[, rendition-set] 

[, rendition-complement] 

[, wrap-flag] [, char-set] 

RETURNS 

VMS Usage: cond—value 
type: longword integer (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display identifier. The display-id argument is the address of an unsigned 
longword that contains the display identifier of the virtual display. 

text 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Text output. The text argument is the address of the descriptor pointing to 
the output string. 

line-adv 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Lines to advance. The line-adv argument is the address of a signed longword 
that contains the number of lines to advance after the output. This argument 
is optional. 
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rendition-set 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Set rendition. The rendition-set argument is the address of an unsigned 
longword that contains attribute information. Each 1-bit attribute in this 
argument causes the corresponding attribute to be set in the display (see 
below for list of the attributes that can be set). 


rendition-complement 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Complement rendition. The rendition-complement argument is the address 
of an unsigned longword that contains attribute information. Each 1- 
bit attribute in this argument causes the corresponding attribute to be 
complemented in the display (see below for a list of the attributes that 
can be set). 


If the same bit is specified in both the rendition-set argument and in the 
rendition-complement argument, the application is rendition-set followed 
by rendition-complement. Using these two arguments together, the caller 
can exercise arbitrary and independent control over each attribute on a single 
call. On an attribute-by-attribute basis the following transformations can be 
caused: 


Set 

Complement 

Action 

0 

0 

Attribute unchanged. 

1 

0 

Attribute set to “on." 

0 

1 

Attribute set to complement of current setting. 

1 

1 

Attribute set to "off." 


Attributes that can be manipulated in this manner are: 


SMG$M_BLINK 
SMG$M_BOLD 
SMG$M_RE VERSE 

SMG$M_ 

UNDERLINE 


Displays characters blinking. 

Displays characters in higher-than-normal intensity. 

Displays characters in reverse video—that is, using the 
opposite default rendition of the virtual display. 

Displays characters underlined. 


wrap-flag 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The value used to determine if wrapping is enabled or not. The wrap-flag 
argument is an unsigned longword that contains this value. A 0 means no 
wrap; a 1 means wrap enabled. If the value is omitted, no wrap is the default. 
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char-set 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the default character set for all text in this virtual display. The 
char-set argument is the address of an unsigned longword that contains 
the character-set code. At this time, the only valid value is SMG$C—ASCII, 
which is also the default. 


DESCRIPTION This routine is used to write lines with double-high and double-wide 

characters to the virtual display. SMG$PUT_LINE_HIGHWIDE writes 



from the current virtual cursor position to the end of the line. If the caller's 
text does not span to the end of the line, blank spaces are added. 

Treatment of text that exceeds the rightmost bounds of the display depends 
on the wrap-flag argument. If the wrap-flag is set, lines are scrolled line-adv 
times to make room for the overflow characters in the "next" line. If wrap is 
off, overflow characters are lost. 

Following a call to SMG$PUT_LINE—HIGHWIDE, the virtual cursor position 
is set to column 1 of the next line where output should occur. The next line 
where output should occur is determined by the line-adv argument. Line- 
adv defaults to 2 so that subsequent calls to SMG$PUT_LINE—HIGHWIDE 
will not cause overprinting. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_WRONUMARG Wrong number (or combination of) arguments. 

LIB$_INVSTRDES Invalid string descriptor. 
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SMG$PUT_LINE_WIDE—Write Double- 

Width Line 

SMG$PUT_LINE_WIDE writes a line of double-width text to a virtual 
display. 


FORMAT SMG$PUT_LINE_WIDE display-id,text 

[,/ine-advance] 

[, rendition-set] 

[, rendition-complement] 
[, wrap-flag] [, char-set] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by value 


ARGUMENTS display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display affected. The display-id argument is the address 
of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE—VIRTUAL —DISPLAY. 


text 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Characters to be written to the virtual display. The text argument is the 
address of a descriptor pointing to the text. 


line-advance 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the number of lines to advance after output. The line-advance 
argument is the address of a signed longword integer that contains the 
number of lines to advance. 


April 1986 


RTL-687 









Run-Time Library Routines 

SMG$PUT_LINE_WIDE 


rendition-set 


VMS Usage: 
type: 
access: 
mechanism: 


mask_longword 
longword (unsigned) 
read only 
by reference 


Mask that denotes video attributes for the drawn line. The rendition-set 
argument is the address of an unsigned longword that contains a video 
attributes mask. Each bit attribute in this argument causes the corresponding 
attribute to be set in the display. 


Video attributes that can be manipulated in this manner are as follows: 


SMG$M_BLINK 
SMG$M_BOLD 
SMG$M_RE VERSE 

SMG$M_UNDERLINE 


Displays blinking characters 

Displays characters in higher-than-normal intensity 

Displays characters in reverse video — that is, 
using the opposite default rendition of the virtual 
display 

Displays underlined characters 


If the same bit is set in both the rendition-set and rendition-complement 
arguments, the Screen Management Facility applies the rendition-set attribute 
followed by the rendition-complement attribute. Using these two arguments, 
the caller can exercise independent control over each attribute in a single call. 


rendition-complement 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Mask that denotes video attributes for the line drawn. The rendition- 
complement argument is the address of an unsigned longword that contains 
a video attributes mask. 


Each bit attribute in this argument causes the corresponding attribute to be 
set in the display. Video attributes that can be manipulated in this manner 
are the same as those for the rendition-set argument. 

The following table shows the action taken by the Screen Management 
Facility for various combinations of rendition-set and rendition-complement 
attributes. 


Set 

Complement 

Action 

0 

0 

Attribute unchanged 

1 

0 

Attribute on 

0 

1 

Attribute set to complement of default setting 

1 

1 

Attribute off 
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wrap-flag 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the action to take if the text does not fit on the line. The wrap-flag 
argument is the address of an unsigned longword that contains the flag. 0 
specifies no wrap (the default) while 1 specifies wrap. 

char-set 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the default character set for all text in this virtual display. The 
char-set argument is the address of an unsigned longword that contains 
the character set code. At this time, the only valid value is SMG$C_ASCII, 
which is also the default. 

DESCRIPTION 

SMG$PUT_LINE_WIDE write lines of double-width text to the virtual 
display. SMG$PUT_LINE_WIDE writes out the entire line, starting at the 
current virtual cursor position. If the caller's text does not span the entire 
line, the line is filled with blanks. 

If wrap-flag is set, lines are scrolled line-advance times to make room for the 
overflow characters in the "next" line. If wrap-flag is clear, excess characters 
are discarded. 

Following a call to SMG$PUT_LINE_WIDE, the virtual cursor position is 
set to column 1 of the next line where output should occur. The next line 
where output should occur is determined by the line-advance argument; 
line-advance defaults to 1 so that subsequent calls to SMG$PUT_LINE will 
not cause overprinting. 

Other procedures that may be used to write text to a virtual display are 
SMG$PUT_LINE and SMG$PUT_LINE_HIGHWIDE. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_INVDIS_ID Invalid display-id. 

SMG$_WRONUMARG Wrong number of arguments. 

LIB$_INVSTRDES Invalid string descriptor. 


EXAMPLE 

C+ 

C This FORTRAN example program demonstrates the use of 
C SMGIPUT.LINE.WIDE. 

C 

C Include the SMG definitions. In particular, we want SMG$M_BORDER and 
C SMG$M_UNDERLINE. 

C- 

INCLUDE '($SMGDEF)' 

INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD 
INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$PUT_LINE_WIDE 
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INTEGER DISPLAY1, PASTE1, ROWS. COLUMNS. STATUS 
CHARACTER*34 TEXT(3) 

C+ 

C Create a virtual display with a border by calling 
C SMG$CREATE_VIRTUAL_DISPLAY. 

C- 

ROWS = 7 
COLUMNS = 70 

STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS. COLUMNS. DISPLAY1, SMG$M_BORDER) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 

C+ 

C Call SMG$CREATE_PASTEBOARD to create the pasteboard. 

C- 

STATUS = SMG$CREATE_PASTEBOARD (PASTED 
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 

C+ 

C Use SMG$PUT_LINE to put data in the virtual display. 

C- 

TEXT(l) = 'This virtual display has 7' 

TEXT(2) * 'rows and 70 columns.' 

TEXT(3) = 'Text entered by SMG$PUT_LINE_WIDE.• 

C+ 

C Alter the first line of text is printed, advance two lines. 

C- 

STATUS = SMG$PUT__LINE_WIDE ( DISPLAY1, TEXT(l), 2) 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 

C+ 

C Underline the next line of text. Notice that 34 characters are being 
C underlined. Advance 1 line of text after displaying the line. 

C- 

STATUS = SMG$PUT_LINE_WIDE ( DISPLAY1, TEXT(2), 1. 

1 SMG$M_UNDERLINE) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 


C+ 

C Display the third line of text. 

C- 

STATUS = SMG$PUT_LINE_WIDE ( DISPLAY1, TEXT(3)) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (ttVAL (STATUS)) 

C+ 

C Paste the virtual display using SMG$PASTE_VIRTUAL_DISPLAY. 

C- 

STATUS * SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4. 5) 
IF (.NOT. STATUS) CALL LIB$SIGNAL(7.VAL(STATUS)) 

END 


The output generated by this FORTRAN program is shown in Figure RTL-30. 
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Figure RTL-30 Output Generated by FORTRAN Program Calling 
SMG$PUT_LINE_WIDE 
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SMG$PUT_PASTEBOARD 
Output Pasteboard via Routine 

SMG$PUT_PASTEBOARD accesses the contents of a pasteboard. 


FORMAT 

SMG$PUT_PASTEBOARD 

pasteboard-id, p-rtn 
f p-prm ,p-ff-flag 

RETURNS 

VMS Usage: 
type: 
access: 
mechanism: 

cond_value 

longword integer (signed) 
write only 
by value 



ARGUMENTS pasteboard-id 

VMS Usage: longworcLunsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Pasteboard identifier. The pasteboard-id argument is the address of an 
unsigned longword containing the pasteboard identifier. 


p-rtn 

VMS Usage: longword_unsigned 
type: procedure entry mask 

access: read only 

mechanism: by reference 

Pasteboard routine. The p-rtn argument is the address of the routine to be 
called. 

p-prm 

VMS Usage: user_arg 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Pasteboard argument. The p-prm argument is a user-specified argument to 
be passed to the action routine. If omitted, a 0 will be passed as the user 
argument. 


p-ff-flag 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

A flag (0 or 1). If 1, then the first line passed to the action routine will be a 
form feed. If not specified, then no form-feed line will be sent. 
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DESCRIPTION 


CONDITION 

VALUES 

SIGNALED 


The SMG$PUT_PASTEBOARD routine accesses the contents of a pasteboard. 
The caller specifies an action routine that will be called once for each line in 
the pasteboard. The action routine will be passed a descriptor for that line 
followed by a user-specified argument. 


descriptor for line 


p-prm argument 
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SS$_NORMAL Normal successful completion. 

Other Error return passed back by an action routine. 
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SMG$PUT_VIRTUAL-DISPLAY-ENCODED 
Write Encoded String To Display 



SMG$PUT_VIRTUAL-DISPLAY-ENCODED lets you write a string 
that has multiple video renditions to a virtual display. 

FORMAT 

SMG$PUT_VIRTUAI_DISPLAY-ENCODED 

display-id ,encoded-length 
, encoded-text [, line-number] 

[, column-number] [ f placeholder-arg] 

[, char-set] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display affected. The display-id argument is the address 
of a signed longword integer that contains the display identifier. 

Display-id is returned by SMG$CREATE—VIRTUAL —DISPLAY. 

encoded-length 

VMS Usage: longword—unsigned 
type. longword (unsigned) 

access: read only 

mechanism: by reference 

Length of the encoded string. The encoded-length argument is the address 
of an unsigned longword that contains the length of the encoded string. 

encoded-text 

VMS Usage: address 
type: unspecified 

access: read only 

mechanism: by reference 

A data structure or record passed by reference. The encoded-text argument is 
the address of the data. 

Encoded-text has three parts: 

• The text to be displayed. 
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• One or more "triplets," each specifying: 1) the starting position of a field 
within the text, 2) the length of the field, and 3) the video rendition for 
that field. 

• An unsigned word integer specifying the number of bytes in encoded-text 
that are not part of the text to be displayed. That is, the number of bytes 
in all triplets, plus two bytes for the unsigned word integer. 

Figure RTL-31 shows the format of the encoded-text argument. 

Figure RTL-31 Format of Encoded Text 


Text of string 


Triplet 

i 


Triplet 

j 


Length of postamble 


(Encoded length- 
length of postamble) 


5 bytes 


5 bytes 


2 bytes 
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Each triplet requires five bytes: 

• Two bytes for an unsigned word integer specifying the starting position of 
the field within the text. The first position is numbered 1. 

• Two bytes for an unsigned word integer specifying the number of bytes in 
the field. 

• One byte specifying the video attributes for the field. 

Each triplet is treated as a self-contained unit, and video attributes are applied 
in the order specified. Thus, if one triplet specifies underlining for character 
positions 1 through 5, and another triplet specifies bolding for character 
positions 3 through 5, bolding overwrites underlining for character positions 
3 through 5. To specify more than one video attribute for a field, use the 
bitwise OR of the video attribute codes. Any text not specified in a triplet is 
displayed with no video attributes. 


line-number 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the line at which output begins. The line-number argument is 
the address of a signed longword integer that contains the line number. If 
line-number is omitted or if it is equal to zero, output begins on the current 
line. 


column-number 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column at which output begins. The column-number argument 
is the address of a signed longword integer that contains the column number. 
If column-number is omitted or if it is equal to zero, output begins on the 
current column. 
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placeholder-arg 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Reserved placeholder. The placeholder-arg argument is a reserved 
placeholder. 

char-set 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the default character set for all text in this virtual display. The 
char-set argument is the address of an unsigned longword that contains 
the character set code. At this time, the only valid value is SMG$C_ASCII, 
which is also the default. 

DESCRIPTION 

SMG$PUT_VIRTUAL-DISPLAY-ENCODED writes the encoded string to 
the specified virtual display. If line-number and column-number are both 
omitted, the string is written starting at the current virtual cursor position. 

If the text does not span the entire line, the remaining space is filled with 
blanks. 

This routine is useful for writing strings in which some but not all characters 
have video renditions, or where different video renditions are desired for the 
same string. 

CONDITION 

VALUES 

RETURNED 

SSS—NORMAL Normal successful completion. 

SMG$_INVARG Invalid argument or combination of arguments. For 

example, one of the attribute triplets may specify 
a starting byte and a number of bytes that extend 
beyond the length of the string. 

SMG$_INVDIS_ID Invalid display-id. 

LIB$_INSVIRMEM Insufficient virtual memory. 
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SMG$PUT_WITH_SCROLL—Write Text 

and Scroll 



SMG$PUT_WITH—SCROLL writes a line of text to a virtual display 
and scrolls the display if necessary. 

FORMAT 

SMG$PUT_WITH—SCROLL 

display-id [, text] 

[, direction] [, rendition-set] 
[,rendition-complement] [, wrap-flag] 

[, char-set] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display affected. The display-id argument is the address 
of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE—VIRTUAL —DISPLAY. 

text 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

The text to be displayed. The text argument is the address of a descriptor 
pointing to the text. 

direction 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the direction to scroll, if scrolling is necessary. The direction 
argument is the address of an unsigned longword that contains the direction 
code. Valid values are SMG$M-UP and SMG$M_DOWN. SMG$M_UP is 
the default. 
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rendition-set 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Mask that denotes video attributes for the drawn line. The rendition-set 


argument is the address of an unsigned longword that contains a video 
attributes mask. Each bit attribute in this argument causes the corresponding 
attribute to be set in the display. 


Video attributes that can be manipulated in this manner are as follows: 


SMG$M_BLINK 

SMG$M_BOLD 

SMG$M_REVERSE 

SMG$M_UNDERLINE 


Displays blinking characters 

Displays characters in higher-than-normal intensity 

Displays characters in reverse video — that is, 
using the opposite default rendition of the virtual 
display 

Displays underlined characters 


If the same bit is set in both the rendition-set and rendition-complement 
arguments, the Screen Management Facility applies the rendition-set attribute 
followed by the rendition-complement attribute. Using these two arguments, 
the caller can exercise independent control over each attribute in a single call. 


rendition-complement 


VMS Usage: 
type: 
access: 
mechanism: 


mask_longword 
longword (unsigned) 
read only 
by reference 


Mask that denotes video attributes for the line drawn. The rendition- 
complement argument is the address of an unsigned longword that contains 
a video attributes mask. 


Each bit attribute in this argument causes the corresponding attribute to be 
set in the display. Video attributes that can be manipulated in this manner 
are the same as those for the rendition-set argument. 

The following table shows the action taken by the Screen Management 
Facility for various combinations of rendition-set and rendition-complement 
attributes. 


Set 

Complement 

Action 

0 

0 

Attribute unchanged 

1 

0 

Attribute on 

0 

1 

Attribute set to complement of default setting 

1 

1 

Attribute off 


wrap-flag 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the action to take if the text does not fit on the line. The wrap-flag 
argument is the address of an unsigned longword that contains the flag. No 
wrap (the default) is 0, while 1 is wrap. 
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char-set 


VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the default character set for all text in this virtual 
char-set argument is the address of an unsigned longword 
the character set code. At this time, the only valid value is 
which is also the default. 


display. The 
that contains 
SMG$C_ASCII, 


DESCRIPTION SMG$PUT_WITH_SCROLL writes text to the specified virtual display 

beginning at the current line. Once text reaches the bottom or top line 
(depending on the scrolling direction), subsequent calls to this routine cause 
the display to scroll. If you do not supply any text, this routine opens a blank 
line. 

If wrap-flag is set, and the text provided exceeds the rightmost boundary of 
the display, another line is written and the display scrolled, if necessary. If 
wrap-flag is off, overflow characters are discarded. 

Note that you cannot use SMG$PUT_WITH—SCROLL to insert a line into 
the middle of a virtual display and scroll the displaced lines. To do this 
you should first redefine the display's scrolling region with SMG$SCROLL_ 
DISPLAY-AREA, then write the line to the beginning of the new scrolling 
region in the virtual display. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_INVDIS_ID 

SMG$_WRONUMARG 

SMG$_INVARG 

LIB$_INVSTRDES 


Normal successful completion. 

Invalid display-id. 

Wrong number of arguments. 

Invalid argument, for example, a direction other 
than up or down. 

Invalid string descriptor. 


EXAMPLE 


C+ 

C This FORTRAN example program demonstrates the use of 
C SMG$PUT_WITH_SCROLL. 

C- 


PARAMETER 

PARAMETER 

PARAMETER 

PARAMETER 

PARAMETER 

PARAMETER 


SMG$M_UP = 1 
SMG$M_D0WN = 2 
SMG$M_B0LD = 1 
SMG$M_REVERSE = 2 
SMG$M_BLINK * 4 
SMG$M_UNDERLINE = 8 


IMPLICIT INTEGERS (A-Z) 


C+ 

C Call SMG$CREATE_PASTEBOARD to establish the terminal screen 
C as a pasteboard. 

C- 

STATUS = SMG$CREATE_PASTEBOARD (NEW.PID) 

IF (.NOT. STATUS) CALL LIB$ST0P C/.VAL (STATUS)) 

C+ 

C Using SMG$CREATE_VIRTUAL_DISPLAY, establish a virtual display region. 
C- 
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STATUS * SMG$CREATE_VIRTUAL_DISPLAY (5,80,DISPLAY_ID) 
IF (.NOT. STATUS) CALL LIB$ST0PC/.VAL(STATUS)) 


C+ 

C Paste the virtual display to the screen, starting at 
C row 10. column 15 by calling SMG$PASTE_VIRTUAL_DISPLAY. 

C- 

STATUS = SMG$PASTE_VIRTUAL.DISPLAY(DISPLAY_ID,NEW_PID,10,15) 
IF (.NOT. STATUS) CALL LIB$ST0P(7.VAL(STATUS)) 

C+ 

C Define a scrolling region through a call to 
C SMG$SET_DISPLAY_SCROLL_REGION. 

C- 


STATUS = SMG$SET_DISPLAY_SCROLL_REGION(DISPLAY.ID,1,5) 

IF (.NOT. STATUS) CALL LIB$ST0PC/.VAL(STATUS)) 

C+ 

C Call SMG$PUT_WITH_SCROLL and SMG$ERASE_LINE to write three 
C scrolling lines to the screen. The first line will be underlined, 

C the second blinking, and the third in reverse video. 

C- 

DO I = 1,10 

IF ((1/2) + (1/2) .EQ. I) THEN 
DIR = SMGlM.UP 

ELSE 

DIR = SMG$M_D0WN 

ENDIF 

STATUS = SMG$PUT_WITH_SCROLL (DISPLAY.ID, 

1 'This line is underlined*.DIR,SMG$M.UNDERLINE,0) 

IF (.NOT. STATUS) CALL LIB$ST0P(%VAL(STATUS)) 

STATUS = SMG$ERASE_LINE(DISPLAY.ID) 

IF (.NOT. STATUS) CALL LIB$ST0POiVAL(STATUS)) 

STATUS = SMG$PUT_WITH_SCROLL (DISPLAY.ID,'This line is blinking', 
1 DIR,SMG$M_BLINK,0) 

IF (.NOT. STATUS) CALL LIB$ST0PC/.VAL(STATUS)) 

STATUS * SMG$ERASE_LINE (DISPLAY.ID) 

IF (.NOT. STATUS) CALL LIB$ST0POiVAL(STATUS)) 

STATUS = SMG$PUT_WITH_SCROLL (DISPLAY.ID,'This line is reverse 
1 video'.DIR,SMG$M_REVERSE.0) 

IF (.NOT. STATUS) CALL LIB$ST0P(‘/.VAL(STATUS)) 

STATUS = SMG$ERASE_LINE (DISPLAY.ID) 

IF (.NOT. STATUS) CALL LIB$ST0P(7.VAL(STATUS)) 

ENDDO 

END 


This FORTRAN program calls Run-Time Library Screen Management routines 
to format screen output. When run, this program displays three scrolling lines 
which, respectively, are underlined, blinking, and in reverse video. Because 
it is not possible to represent scrolling (or blinking text) in a diagram, it is 
suggested that you run this example to observe the output. 
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SMG$READ_COMPOSED_LINE—Read Com 

posed 

Line 



SMG$READ_COMPOSED_LINE reads a line of input composed of 
normal keystrokes and equivalence strings. 

FORMAT 

SMG$READ_COMPOSED_LINE 

keyboard-id, key-table-id 
, received-text [, prompt-string] 

[, received-string-length] 

[, display-id] [, function-keys-flag] 

[, ini-string] [, timeout] 

[, rendition-set] 

[,rendition-complement] 

[, terminator-code] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

keyboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual keyboard from which input is to be read. The keyboard- 
id argument is the address of an unsigned longword that contains the 
keyboard identifier. 

Keyboard-id is returned by SMG$CREATE-VIRTUAL-KEYBOARD. 

key-table-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the key table to be used for translating keystrokes. The key-table-id 
argument is the address of an unsigned longword that contains the key table 
identifier. 

Key-table-id is returned by SMG$CRE ATE-KEY-TABLE. 
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received-text 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

String into which SMG$READ_COMPOSED_LINE writes the complete 
composed line. The received-text argument is the address of a descriptor 
pointing to the storage in which the composed line is written. 

prompt-string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String used to prompt for the read operation. The prompt-string argument is 
the address of a descriptor pointing to the prompt string. 


received-string-length 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Receives the number of characters read or the maximum length of received- 
text, whichever is less. The received-string-length argument is the address 
of an unsigned longword into which SMG$READ__COMPOSED_LINE writes 
the number of characters read. 


display-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display identifier. The display-id argument is the address of an unsigned 
longword that contains the display identifier. This argument is optional only 
if you are not using the Screen Management Facility's output routines. 


If you are using the Screen Management Facility input and output routines, 
this argument specifies the virtual display in which the input is to occur. The 
virtual display specified must be pasted to the same terminal as specified by 
keyboard-id and must not be occluded. 


The input begins at the current virtual cursor position but the virtual cursor 
must be in column 1. Note that the length of the prompt-string plus the 
input is limited to the number of visible columns in the display. 


Note: This virtual display must be pasted in column 1 and may not have any 
other virtual displays to its right. This restriction is necessary because 
otherwise any occurrence of CTRL/R or CTRL/U would blank out the 
entire line, including any output pasted to the right. To circumvent this 
restriction, you may use SMG$REPAINT_LINE whenever a CTRL/R or 
CTRL/U is encountered. 
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function-keys-flag 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Function keys. The function-keys-flag argument is the address of an 
unsigned longword. If function-keys-flag equals 1, then the function keys 
can be used and line editing is disabled. If function-keys-flag equals zero, 
line editing is enabled and the function keys cannot be used. 

ini-string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Optional string that contains the initial characters of the field. The ini-string 
argument is the address of a descriptor pointing to the string. 


timeout 

VMS Usage: longword—signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Optional timeout count. The timeout argument is the address of a signed 
longword containing the timeout count. If the timeout argument is specified, 
all characters entered before the timeout are returned in the buffer. If the 
timeout argument is omitted, characters are returned in the buffer until a 
terminator is encountered. 


rendition-set 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Optional attribute specifier. The rendition-set argument is the address of a 
longword bit mask in which each 1-bit attribute causes the corresponding 
attribute to be set in the display. The following attributes can be specified by 
the rendition-set argument: 


SMG$M_BLINK 

SMG$M_BOLD 

SMG$M_RE VERSE 

SMG$M_UNDERLINE 


Displays characters blinking. 

Displays characters in higher-than-normal intensity 
(bolded). 

Displays characters in reverse video — that is, using the 
opposite default rendition of the virtual display. 

Displays characters underlined. 


The display-id argument must be specified when using the rendition-set 
argument. 
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rendition-complement 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Optional attribute complement specifier. The rendition-complement 
argument is the address of a longword bit mask rendition-set in which 
each 1-bit attribute causes the corresponding attribute to be complemented in 
the display. All of the attributes that can be specified with the rendition-set 
argument can be complemented with the rendition-complement argument. 
The display-id argument must be specified when the rendition-complement 
argument is used. 


terminator-code 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Key terminator code. The terminator-code argument is an unsigned word 
into which is written a code indicating what character or key terminated the 
read. Key terminator codes are of the form SMG$K_TRM_keyname. The 
key names are listed in Table RTL-1, in Chapter 3. 


DESCRIPTION SMG$READ_COMPOSED_LINE reads a line composed of normal keystrokes 

and key equivalence strings as defined in the specified key table. Attributes 
of the key definition control whether the equivalence string is echoed and 
whether the read terminates with the defined keystroke. Normal keystrokes 
are always echoed. 

The optional arguments rendition-set and rendition-complement let the 
user control the attributes of the virtual display in which the read is done. 
The rendition-set argument sets certain virtual display attributes, while 
rendition-complement complements these attributes. If the same bit is 
specified in both the rendition-set and rendition-complement parameters, 
the rendition-set is evaluated first, followed by the rendition-complement. 
By using these two parameters together, the user can control each virtual 
display attribute in a single procedure call. On a single attribute basis, the 
user can cause the following transformations: 


Set 

Complement 

Action 

0 

0 

Attribute unchanged. 

1 

0 

Attribute set to "on." 

0 

1 

Attribute set to complement of current setting. 

1 

1 

Attribute set to "off." 


A carriage return always terminates the read operation. If CTRL/Z is typed 
and there is no definition for CTRL/Z in the key definition table, "EXIT" is 
echoed and the read is terminated. If CTRL/Z was the first character typed 
on the line, SMG$_EOF is returned. Otherwise, SMG$_EOF is returned 
on the next read operation. SMG$_EOF is also returned if RMS is used for 
the input operation and it returns RMS$_EOF. No other terminators are 
recognized except those specified as attributes in a key definition. 
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If the arrow keys and CTRL/B are not defined, the previous lines read with 
the SMG$READ_xxxx routines can be recalled using the arrow keys. The 
number of lines saved for later recall depends upon the recall-size argument 
in SMG$CREATE—VIRTUAL —KEYBOARD. The default is 20 lines. 

Note that SMG$READ_COMPOSED—LINE calls the SMG$FLUSH-BUFFER 
routine before performing the input operation. This ensures that the screen 
image is up to date at the time of the input operation. Display batching 
for both the pasteboard and virtual display must be off when you use 
SMG$READ_COMPOSED—LINE. 


CONDITION 

VALUES 

RETURNED 


SSS—NORMAL 

SS$_CANCEL 

SS$_ABORT 

SMG$_EOF 

SMG$_INVDIS_ID 

SMG$_INVKBD_ID 

SMG$_INVKTB_ID 

SMG$_WRONUMARG 

SMG$_ILLBATFNC 

SMG$_INVCOL 


Normal successful completion. 

I/O operation canceled while queued (by 
SMG$CANCEI_INPUT). 

I/O operation aborted during execution (by 
SMG$CANCEI_INPUT). 

End of file. 

Invalid display-id. 

Invalid keyboard-id. 

Invalid key-table-id. 

Wrong number of arguments. 

Input not allowed from a batched display. 

Invalid column. The read operation attempts to 
use a column outside the virtual display. 


Any condition values returned by LIB$COPY_R_DX. 

Any condition values returned by $GET (except RMS$_EOF). 
Any condition values returned by $QIOW. 


April 1986 


RTL-705 











Run-Time Library Routines 

SMG$READ_FROM_DISPLAY 


SMG$READ_FROM_ DISPLAY—Read 

Text from 
Display 



SMG$READ_FROM_DISPLAY reads a line of text from a virtual 
display. 

FORMAT 

SMG$READ_FROM_DISPLAY 

display-id ,returned-string 
[, terminator-string][,row] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display from which text is read. The display-id argument 
is the address of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE—VIRTUAL—DISPLAY. 

returned-string 

VMS Usage: char—string 
type: character string 

access: write only 

mechanism: by descriptor 

String into which SMG$READ_FROM—DISPLAY writes the information read 
from the virtual display. The returned-string argument is the address of a 
descriptor pointing to the storage into which the string is written. 

terminator-string 

VMS Usage: char—string 
type: character string 

access: read only 

mechanism: by descriptor 

String containing a terminator or terminators that end the backward search, 
thus determining the starting position of the returned string. The terminator¬ 
string argument is the address of a descriptor pointing to the string of 
terminators. If omitted, no back searching is performed; the returned string 
starts with the character at the current cursor position. 
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row 


VMS Usage: longword_signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

The row argument is the address of a signed longword that contains the row 
of the display-id to read from. This is an optional argument. 


DESCRIPTION SMG$READ_FROM—DISPLAY returns a string that contains some or all of 

the text on the current line of the specified virtual display. If the terminator¬ 
string argument is omitted, the contents of the current line (from the current 
column position to the rightmost column position) are returned. If the row 
argument is passed, the contents of line row from column 1 to the rightmost 
column is returned in returned-string. If the row argument is passed, the 
terminator-string argument is ignored. 

If you specify a terminator-string, each character in it serves as a terminator 
for "back searching," that is, the process of determining the first character 
position to be returned. If none of the specified terminators are encountered, 
the search is terminated at the first character position on the line. 

Note that SMG$READ_FROM-DISPLAY calls the SMG$FLUSH —BUFFER 
routine before performing the input operation. This ensures that the screen 
image is up to date at the time of the read operation. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_INVDIS_ID 

LIB$_INVSTRDES 

LIB$_INSVIRMEM 


Normal successful completion. 
Invalid display-id. 

Invalid string descriptor. 
Insufficient virtual memory. 


EXAMPLE 


C+ 

C This FORTRAN example demonstrates the use of SMG$READ_FROM_DISPLAY. 

C- 

C+ 

C Include the SMG definitions. In particular, we want SMG$M_BORDER. 

C- 

IMPLICIT INTEGER (A-Z) 

INCLUDE '($SMGDEF)' 

CHARACTER*80 TEXT 

C+ 

C Use SMG$CREATE_VIRTUAL_DISPLAY to create the virtual display 
C and give it a border. 

C- 

ROWS = 5 
COLUMNS = 60 

STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 

C+ 

C Create the pasteboard by calling SMG$CREATE_PASTEBOARD. 

C- 

STATUS = SMG$CREATE_PASTEBOARD (PASTED 
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
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C+ 

C Call SMG$PASTE_VIRTUAL_DISPLAY and SMGlPUT.LINE to paste 
C the virtual display and put some text on line 2. 

C- 

STATUS * SMG|PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 2, 10) 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 

STATUS = SMGlPUT.LINE (DISPLAY1, ' ') 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 

STATUS = SMGlPUT.LINE (DISPLAY1, 

1 'This is an example of using SMGlREAD.FROM.DISPLAY.') 

IF (.NOT. STATUS) CALL LIBlSIGNAL(%VAL(STATUS)) 

C+ 

C Use SMG$READ_FROM_DISPLAY to read line 2 from the virtual 
C display, starting at column 22. 

C- 

STATUS * SMGlSET.CURSOR.ABS ( DISPLAY1, 2, 22) 

IF (.NOT. STATUS) CALL LIBlSIGNAL(%VAL(STATUS)) 

C+ 

C Search line 2 from column 22 to column 1 for the null string. 

C Since no terminator will be supplied, no "back-searching" will take 
C place. TEXT will be assigned the "value" of the line from 
C column 22 to the rightmost column. 

C- 

STATUS « SMGlREAD.FROM.DISPLAY ( DISPLAY1, TEXT) 

IF (.NOT. STATUS) CALL LIBlSIGNALOiVAL(STATUS)) 

C+ 

C Put the line of text found into the virtual display at row 4, 

C column 10 by calling SMG|SET_CURSOR_ABS and SMGlPUT.LINE. 

C- 

STATUS » SMGlSET.CURSOR.ABS ( DISPLAY1, 4, 10) 

IF (.NOT. STATUS) CALL LIBISIGNAL(%VAL(STATUS)) 

STATUS « SMGlPUT.LINE (DISPLAY1, TEXT) 

IF (.NOT. STATUS) CALL LIBlSIGNAL(%VAL(STATUS)) 

C+ 

C Use SMGlSET.CURSOR.ABS to set the cursor back to line 2, column 22. 

C- 

STATUS = SMGlSET.CURSOR.ABS ( DISPLAY1, 2, 22) 

IF (.NOT. STATUS) CALL LIBlSIGNALC/.VAL(STATUS) ) 

C+ 

C Use SMGlREAD.FROM.DISPLAY to search line 2 from column 22 to 
C column 1 for an "f". Now, "back-searching" will take place. 

C Starting at column 22, "back-track" to column 1 looking for "f". 

C Text will then be assigned the "value" of the line from the 
C present cursor position (where the "f" is, to the rightmost 
C column. 

C- 

STATUS * SMGlREAD.FROM.DISPLAY ( DISPLAY1, TEXT, 'f') 

IF (.NOT. STATUS) CALL LIBlSIGNAL OiVAL(STATUS)) 

C+ 

C Put the line of text found into the virtual display at row 4, column 10. 
C- 

STATUS = SMGISET.CURSOR.ABS ( DISPLAY1, 5, 10) 

IF (.NOT. STATUS) CALL LIBlSIGNAL(XVAL(STATUS)) 

STATUS * SMGIPUT.LINE (DISPLAY1, TEXT) 

IF (.NOT. STATUS) CALL LIBlSIGNAL(7.VAL(STATUS)) 

END 


The output generated by this FORTRAN program is shown in Figure RTL-32. 
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Figure RTL-32 Output Generated by FORTRAN Program Calling 
SMG$READ_FROM_DISPLAY 
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SMG$READ_KEYSTROKE—Read a Single 

Character 



SMG$READ_KEYSTROKE reads a keystroke and returns that 
keystroke's terminator code. 

FORMAT 

SMG$READ_KEYSTROKE keyboard-id 

, terminator-code 
[,prompt-string] 

[, timeout] [, display-id] 

[, rendition-set] 

[, rendition-complement] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

keyboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Keyboard identifier. The keyboard-id argument is an unsigned longword 
containing the identification of the virtual keyboard from which to read. 

A virtual keyboard is created by calling the SMG$CREATE—VIRTUAL — 
KEYBOARD routine. 

terminator-code 

VMS Usage: word—unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Key terminator code. The terminator-code argument is an unsigned word 
into which is written a code indicating what character or key terminated the 
read. Key terminator codes are of the form SMG$K_TRM—keyname. The 
key names are listed in Table RTL-1, (Section 3.5.1) in Part I, Chapter 3 of 
this manual. 
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prompt-string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Prompt string. The prompt-string argument is an optional string that is used 
as the prompt for the read operation. 


timeout 


VMS Usage: longword_signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Timeout count. The timeout argument is optional, 
typed before the timeout is returned in the buffer. 


If specified, any character 


display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display identifier. The optional display-id argument is the address of an 
unsigned longword that contains the identifier of the virtual display in which 
the read is to be performed. If the optional prompt-string argument is 
specified while there are multiple virtual displays pasted, the display-id 
argument is required to determine in which virtual display the prompt string 
will be written. If the prompt-string argument is not specified, then do not 
specify the display-id argument. 

In the case of multiple virtual displays, each virtual display has an associated 
virtual cursor position. At the same time, there is a single physical cursor 
position corresponding to the current location of the physical cursor. If the 
display-id argument is specified, the read begins at the current virtual cursor 
position in the specified virtual display. If omitted, the read begins in the 
current physical cursor position. Note that the length of the prompt-string 
plus the key entered is limited to the number of visible columns in the 
display. 


rendition-set 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Attribute specifier. The optional rendition-set argument is the address of a 
longword bit mask in which each 1-bit attribute causes the corresponding 
attribute to be set in the display. The following attributes can be specified by 
the rendition-set argument: 
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SMG$M_BLINK 

SMG$M_BOLD 

SMG$M_RE VERSE 

SMG$M—UNDERLINE 


Displays characters blinking. 

Displays characters in higher-than-normal intensity 
(bolded). 

Displays characters in reverse video — that is, using the 
opposite default rendition of the virtual display. 

Displays characters underlined. 


The display-id argument must be specified when using the rendition-set 
argument. 


rendition-complement 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Attribute complement specifier. The optional rendition-complement 
argument is the address of a longword bit mask in which each 1-bit attribute 
causes the corresponding attribute to be complemented in the display. All 
of the attributes that can be specified with the rendition-set argument can 
be complemented with the rendition-complement argument. The display- 
id argument must be specified when using the rendition-complement 
argument. 


DESCRIPTION SMG$READ_KEYSTROKE reads a keystroke from the virtual keyboard 

specified and returns the terminator code of that keystroke in the form 
SMG$K_TRM—keyname. The keystroke entered to be read is not echoed 
on the screen. This keystroke may be any standard alphabetic character, any 
keypad or function key, or one of the directional arrows. 

The optional arguments rendition-set and rendition-complement let the 
user control the attributes of the virtual display in which the prompt-string 
is printed. The rendition-set argument sets certain virtual display attributes, 
while rendition-complement complements these attributes. If the same bit 
is specified in both the rendition-set and rendition-complement parameters, 
the rendition-set is evaluated first, followed by the rendition-complement. 
By using these two parameters together, the user can control each virtual 
display attribute in a single procedure call. On a single-attribute basis, the 
user can cause the following transformations: 


Set 

Complement 

Action 

0 

0 

Attribute unchanged. 

1 

0 

Attribute set to "on." 

0 

1 

Attribute set to complement of current setting. 

1 

1 

Attribute set to "off." 


Note that display batching for both the pasteboard and the virtual display 
must be off when you use SMG$READ_KEYSTROKE. 
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CONDITION 

SS$_NORMAL 

Normal successful completion. 

VALUES 

SS$_CANCEL 

I/O operation canceled while queued (by 

RETURNED 

SS$_ABORT 

SMG$CANCEL—INPUT). 


I/O operation aborted during execution (by 
SMGSCANCEL—INPUT). 


SMG$_EOF 

End-of-file. 


SMG$_INVDIS_ID 

Invalid display-id. 


SMG$_INVKBD_ID 

Invalid keyboard-id. 


SMG$_WRONUMARG 

Wrong number of arguments. 


LIB$_xxx 

Any error from LIB$SCOPY_R_DX. 


RMS$_xxx 

Any error from $GET (except RMS$_EOF). 


SS$_xxx 

Any error from SQIOW. 


EXAMPLES 


C This FORTRAN example program demonstrates the use of 
C SMG$READ_KEYSTROKE. 

C- 

C+ 

C This routine creates a virtual display and writes it to the pasteboard. 

C Data is placed in the virtual display via SMG$PUT_CHARS. 

C 

C First, include the SMG definitions. In particular, we want SMG$M_BORDER. 
C- 

IMPLICIT INTEGER (A-Z) 

INCLUDE '($SMGDEF) 1 
CHARACTER*3 TEXT 
CHARACTER*27 TEXT.OUTPUT 

C+ 

C Use SMG$CREATE_VIRTUAL_DISPLAY to create a virtual 
C display with a border. 

C- 

ROWS = 7 
COLUMNS = 60 

STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS, COLUMNS, DISPLAYi, SMG$M_BORDER) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(7.VAL(STATUS)) 

C+ 

C Create the pasteboard using SMG$CREATE_PASTEBOARD. 

C- 

STATUS = SMG$CREATE_PASTEBOARD (PASTED 
IF (.NOT. STATUS) CALL LIB$SIGNAL C/.VAL (STATUS) ) 

C+ 

C Use SMG$CREATE_VIRTUAL_KEYBOARD to create a virtual keyboard. 

C- 

STATUS = SMG$CREATE_VIRTUAL_KEYBOARD ( KEYBOARD1) 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 

C+ 

C Using SMG$PASTE_VIRTUAL_DISPLAY, paste the virtual display 
C at row 3, column 9. 

C- 

STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAYI, PASTE1, 3, 9) 

IF (.NOT. STATUS) CALL LIB$SIGNAL C/.VAL (STATUS)) 

STATUS = SMG$PUT_LINE (DISPLAYI, 

1 'Enter the character K after the » prompt.') 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 
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STATUS = SMG$PUT_LINE (DISPLAY1, 

1 'This character will not be echoed as you type it.') 

IF (.NOT. STATUS) CALL LIB$SIGNAL(*/.VAL(STATUS)) 

STATUS = SMG$PUT_LINE (DISPLAY1, 

1 'The terminal character equivalent of K is displayed.') 

IF (.NOT. STATUS) CALL LIB$SIGNAL(7.VAL(STATUS)) 

STATUS = SMG$PUT_LINE (DISPLAY1, ' ') 

IF (.NOT. STATUS) CALL LIBlSIGNAL (7.VAL (STATUS) ) 

C+ 

C Call SMG$READ_KEYSTROKE to read a keystroke from the virtual 
C pasteboard. 

C- 

STATUS = SMG$READ_KEYSTROKE ( KEYBOARD 1, TERM.CHAR, '»', , 

1 DISPLAY1) 

IF (.NOT. STATUS) CALL LIBlSIGNALC/.VAL(STATUS)) 

STATUS = SMGlPUT.LINE (DISPLAY1, ' ') 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 

C+ 

C Use OTSICVT.L.TI to convert the decimal value of TERM_CHAR to 
C a decimal ASCII text string. 

C- 

STATUS = OTS$CVT_L_TI( TERM.CHAR, TEXT) 

IF (.NOT. STATUS) CALL LIBlSIGNALC/.VAL(STATUS)) 

TEXT.OUTPUT = ' TERMINAL CHARACTER IS: • // TEXT 


C+ 

C Call SMGIPUT.LINE and SMGlPUT.CHARS to print the decimal 
C ASCII text string. 

C- 

STATUS = SMGIPUT.LINE (DISPLAY1, TEXT.OUTPUT) 

IF (.NOT. STATUS) CALL LIBlSIGNAL(7.VAL(STATUS)) 

STATUS * SMGIPUT.CHARS (DISPLAY1, TEXT, 7, 25) 

IF (.NOT. STATUS) CALL LIBlSIGNAL(7.VAL(STATUS)) 

END 


The output generated by this FORTRAN program is shown in Figure RTL-33. 
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Figure RTL-33 Output Generated by FORTRAN Program Calling 

SMG$READ_KEYSTROKE 
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S 1 OPTION TYPE=EXPLICIT 

! + 

! This routine demonstrates the use of SMG$READ_KEYSTROKE to read 
! a keystroke from the terminal. 

j 

! Build this program using the following commands. 

! 

!$ BASIC READ.KEY 
!$ CREATE SMGDEF.MAR 

! .TITLE SMGDEF - Define SMG$ constants 

! .Ident /1-000/ 

j 

! $SMGDEF GLOBAL 

j 

! .END 

!$ MACRO SMGDEF 

!$ LINK READ.KEY,SMGDEF 


DECLARE LONG kb_id, ret_status, term.code, I, timer 
EXTERNAL SUB LIB$SIGNAL( LONG BY VALUE ) 

EXTERNAL SUB LIB$STOP( LONG BY VALUE ) 

EXTERNAL LONG CONSTANT SS$_TIMEOUT 
EXTERNAL LONG CONSTANT SMG$K_TRM_PF1 
EXTERNAL LONG CONSTANT SMG$K_TRM_PERIOD 
EXTERNAL LONG CONSTANT SMG$K_TRM_UP 
EXTERNAL LONG CONSTANT SMG$K_TRM_RIGHT 
EXTERNAL LONG CONSTANT SMG$K_TRM_F6 
EXTERNAL LONG CONSTANT SMG$K_TRM_F20 
EXTERNAL LONG CONSTANT SMG$K_TRM_FIND 
EXTERNAL LONG CONSTANT SMG$K_TRM_NEXT_SCREEN 
EXTERNAL LONG CONSTANT SMG$K_TRM_TIMEOUT 

EXTERNAL LONG FUNCTION SMG$CREATE_VIRTUAL_KEYBOARD( LONG, STRING 
EXTERNAL LONG FUNCTION SMG$DELETE_VIRTUAL_KEYBOARD( LONG ) 
EXTERNAL LONG FUNCTION SMG$READ_KEYSTROKE( LONG, LONG, STRING, & 


) 
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LONG, LONG ) 

! + 

! Prompt the user for the timer value. A value of 0 will cause 
! the type ahead buffer to be read. 

j - 

INPUT "Enter timer value (0 to read typeahead buffer): ";timer 
• + 

! Establish a SMG connection to SYS$INPUT. Signal any unexpected 
! errors. 


ret.status = SMG|CREATE_VIRTUAL_KEYBOARD( kb.id, "SYSlINPUT:" ) 
IF (ret.status AND 17.) = 07. THEN 
CALL LIB$SIGNAL( ret.status ) 

END IF 


Read a keystoke, tell the user what we found. 


ret.status = SMG$READ_KEYSTROKE( kb.id, term.code, , timer, ) 

IF (ret.status <> SS$_TIME0UT) AND ((ret.status AND 17.) = 07.) THEN 
CALL LIB$SIGNAL( ret.status ) 

END IF 

PRINT "term.code = ";term_code 
SELECT term.code 
CASE 0 TO 31 

PRINT "You typed a control character" 

CASE 32 TO 127 

PRINT "You typed: ";CHR|(term.code) 

CASE SMG$K_TRM_PF1 TO SMG$K_TRM_PERIOD 

PRINT "You typed one of the keypad keys" 

CASE SMGlK.TRM.UP TO SMG$K_TRM_RIGHT 

PRINT "You typed one of the cursor positioning keys" 

CASE SMG$K_TRM_F6 TO SMG$K_TRM_F20 

PRINT "You typed one of the function keys" 

CASE SMGlK.TRM.FIND TO SMGlK.TRM.NEXT.SCREEN 
PRINT "You typed one of the editing keys" 

CASE SMGlK.TRM.TIMEOUT 

PRINT "You did not type a key fast enough" 

CASE ELSE 

PRINT "I'm not sure what key you typed" 

END SELECT 
! + 

! Close the connection to SYSlINPUT, and signal any errors. 

i - 

ret.status = SMGlDELETE.VIRTUAL.KEYBOARD( kb.id ) 

IF (ret.status AND 17.) = 07. THEN 
CALL LIB$SIGNAL( ret.status ) 

END IF 

END 


This BASIC program reads a keystroke and returns the term_code and the 
name of the keystroke entered. One sample of the output generated by this 
program is as follows: 

$ BASIC READ.KEY 
$ MACRO SMGDEF 
$ LINK READ.KEY,SMGDEF 
$ RUN READ.KEY 

Enter the timer value (0 to read typeahead buffer): ? 9 

term.code * 100 
You typed: d 

Note that in this example, the user entered the keystroke "d” following the 
first prompt. The keystroke entered was not echoed. 
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SMG$READ_STRIIMG—Read String 



SMG$READ_STRING reads a string from a virtual keyboard. 

FORMAT 

SMG$READ_STRING keyboard-id,received-text 

[, prompt-string] 

[,max-length] 

[, modifiers] [, timeout] 

[, terminator-set] 

[, received-string-length] 

[, terminator-code] 

[, display-id] 

[, ini-string] [, rendition-set] 

[, rendition-complement] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

keyboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual keyboard from which input is to be read. The keyboard- 
id argument is the address of an unsigned longword that contains the 
keyboard identifier. 

Keyboard-id is returned by SMG$CREATE-VIRTUAL-KEYBOARD. 

received-text 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

String into which the input line is written. The received-text argument is the 
address of a descriptor pointing to the storage into which the text is written. 

prompt-string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String used to prompt for the read operation. The prompt argument is the 
address of a descriptor pointing to the prompt string. 
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max-length 


VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the maximum number of characters to be read. The max-length 
argument is the address of a signed longword integer that contains the 


maximum number of characters to be read. The maximum valid value for this 
argument is 512. If omitted, 512 is the default. 


modifiers 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Bit mask that specifies optional behavior. The modifiers argument is the 
address of an unsigned longword that contains the bit mask. 

Valid modifiers are: 


• TRM$ M _TM _C VTLO W 

• TRM$M_TM—NOECHO 

• TRM$M _TM —PURGE 

• TRM$M_TM_TRMNOECHO 

• TRM$M_TM—NOEDIT 

• TRM$M-TM_NORECALL 


See the terminal driver section of the VAX/VMS I/O User's Reference Manual: 
Part I for more information on modifiers. The TRM$ symbols are defined by 
the $TRMDEF macro/module in DIGITAL-supplied system symbol libraries. 

timeout 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the number of seconds allowed between the time the prompt is 
issued and the completion of the input operation. The timeout argument is 
the address of a signed longword integer that contains the number of seconds. 

If timeout is specified, all characters typed before the expiration time are 
returned in received-text. If omitted, the input operation remains active until 
a terminator is typed. 


terminator-set 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor, fixed length 

Either a mask that specifies which characters are to be treated as terminators 
(short form) or a descriptor pointing to such a mask (long form). The 
terminator-set argument is the address of a descriptor pointing to the mask. 
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If you want to use terminators with ASCII values in the range 0 to 31, use 
the short form: You create this mask by setting the bit that corresponds to 
the ASCII value of desired terminator. For example, to specify that CTRL/A 
(ASCII value 1) is a terminator, you set bit 1 in the terminator-set mask. 

If you want to use terminators with ASCII values outside the range 0 to 31, 
use the long form; you first create a descriptor of this form: 


31_ 16 15 0 


(not used) 

mask size in bytes 

address of mask 
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The mask itself has the same format as that of the short form; however, the 
long form allows use of a more comprehensive set of terminator characters. 
For example, a mask size of 16 bytes allows any 7-bit ASCII character to be 
set as a terminator, while a mask size of 32 bytes allows any 8-bit character to 
be set as a terminator. Any mask size between 1 and 32 bytes is acceptable. 

If the terminator mask is all zeros, there are no specified terminators and the 
read terminates when the number of characters specified in the max-length 
argument have been transferred. 

If the terminator-set argument is omitted, the set of terminators is the VMS 
default terminator set. For more information see the VAX/VMS I/O User's 
Reference Manual: Part I, Section 8.4.1.2. 


received-string-length 


VMS Usage: 
type: 
access: 
mechanism: 


word-unsigned 
word (unsigned) 
write only 
by reference 


Receives the number of characters read or the maximum size of received- 
text, whichever is less. The received-string-length argument is the address 
of an unsigned word into which is written the number of characters or the 
maximum size. 


terminator-code 


VMS Usage: 
type: 
access: 
mechanism: 


word—unsigned 
word (unsigned) 
write only 
by reference 


Key terminator code. The terminator-code argument is an unsigned word 
into which is written a code indicating what character or key terminated the 
read. Key terminator codes are of the form SMG$K_TRM—keyname. The 
keynames are listed in Table RTL-1, in Chapter 3. 
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display-id 


VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display identifier. The display-id argument is the address of an unsigned 
longword that contains the display identifier. 


This argument is optional only if you are not using the Screen Management 
Facility's output routines. 


If you are using the Screen Management Facility input and output routines, 
this argument specifies the virtual display in which the input is to occur. The 
virtual display specified must be pasted to the same terminal as specified by 
keyboard-id and must not be occluded. 

This virtual display must be pasted in column 1 and may not have any 
other virtual displays to its right. This restriction applies because otherwise 
the occurrence of a CTRL/R or CTRL/U would cause the entire line to be 
blanked, including any output to the right. To circumvent this restriction, 
you may use SMG$REPAINT_LINE to repaint the line when a CTRL/R or 
CTRL/U is detected. 


The input begins at the current cursor position but the cursor must be in 
column 1. Note that the length of the prompt plus the input is limited to the 
number of visible columns in the display. 


ini-string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Initial character string. The ini-string argument is the address of a descriptor 
pointing to the optional string that contains the initial characters of the field. 


rendition-set 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Attribute specifier. The optional rendition-set argument is the address of a 
longword bit mask in which each 1-bit attribute causes the corresponding 
attribute to be set in the display. The following attributes can be specified 
using the rendition-set argument: 


SMG$M_BLINK 

SMG$M_BOLD 

SMG$M_RE VERSE 

SMG$M_UNDERLINE 


Displays characters blinking. 

Displays characters in higher-than-normal intensity 
(bolded). 

Displays characters in reverse video — that is, using the 
opposite default rendition of the virtual display. 

Displays characters underlined. 


The display-id argument must be specified when using the rendition-set 
argument. 
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rendition-complement 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Attribute complement specifier. The optional rendition-complement 
argument is the address of a longword bit mask in which each 1-bit attribute 
causes the corresponding attribute to be complemented in the display. All of 
the attributes that can be specified with the rendition-set argument can be 
complemented with rendition-complement. The display-id argument must 
be specified when using the rendition-complement argument. 


DESCRIPTION SMG$READ_STRING returns a string of characters read from a virtual 

display. Note that display batching for both the pasteboard and the virtual 
display must be off when you use SMG$READ_STRING. 

The optional arguments rendition-set and rendition-complement let the 
user control the attributes of the virtual display in which the read is done. 
The rendition-set argument sets certain virtual display attributes, while 
rendition-complement complements these attributes. If the same bit is 
specified in both the rendition-set and rendition-complement parameters, 
the rendition-set is evaluated first, followed by rendition-complement. By 
using these two parameters together, the user can control each virtual display 
attributes in a single procedure call. On a single-attribute basis, the user can 
cause the following transformations: 


Set 

Complement 

Action 

0 

0 

Attribute unchanged. 

1 

0 

Attribute set to "on." 

0 

1 

Attribute set to complement of current setting. 

1 

1 

Attribute set to "off." 


Note that the text read by SMG$READ_STRING is saved for later recall with 
SMG$READ_COMPOSED_LINE. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SS$_CANCEL 

SS$_ABORT 


SMGS—EOF 

SMG$_INVDIS_ID 

SMG$_INVKBD_ID 

SMG$_INVKTB_ID 

SMG$_WRONUMARG 

SMG$_ILLBATFNC 

SMG$_INVCOL 


Normal successful completion. 

I/O operation canceled while queued (by 
SMGSCANCEI_INPUT). 

I/O operation aborted during execution (by 
SMGSCANCEI_INPUT). 

End of file. 

Invalid display-id. 

Invalid keyboard-id. 

Invalid key-table-id. 

Wrong number of arguments. 

Input not allowed from a batched display. 

Invalid column. The input occurs outside the virtual 
display. 
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SMGS—INVMAXLEN Maximum length specified was greater than 512. 

Any condition values returned by LIB$COPY_R_DX. 

Any condition values returned by $GET (except RMS$_EOF). 

Any condition values returned by $QIOW. 


EXAMPLES 

1 OPTION TYPE=EXPLICIT 


This routine demonstrates the use of SMG$READ_STRING to read 
either a string, a control key, or a keypad key. 

Build this program using the following commands. 

$ BASIC SMGTEST 
$ CREATE SMGDEF.MAR 

.TITLE SMGDEF - Define SMG$ constants 
.Ident /1-000/ 

$SMGDEF GLOBAL 

.END 

$ MACRO SMGDEF 
$ LINK SMGTEST,SMGDEF 


DECLARE LONG KB.ID, RET.STATUS, STR 
DECLARE STRING DATA.STR, TERM.SET 
EXTERNAL LONG CONSTANT IO$M_TIMED 
LONG CONSTANT I0$M_N0ECH0 
LONG CONSTANT IOlM.NOFILTR 
SUB LIB$SIGNAL( LONG BY VALUE 
SUB LIB$ST0P( LONG BY VALUE ) 


LEN, TERM.CODE, MODIFIER, I, TIMER 


EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

LONG 


) 


LONG CONSTANT SS$_TIMEOUT 

LONG CONSTANT SMG$K_TRM_PF1 

LONG CONSTANT SMG$K_TRM_PERIOD 

LONG CONSTANT SMG$K_TRM_UP 

LONG CONSTANT SMG$K_TRM_RIGHT 

LONG CONSTANT SMG$K.TRM_F6 

LONG CONSTANT SMG$K_TRM_F20 

LONG CONSTANT SMG$K_TRM_E1 

LONG CONSTANT SMG$K_TRM_E6 

LONG CONSTANT SMG$K_TRM_TIMEOUT 

LONG FUNCTION SMG$CREATE_VIRTUAL_KEYBOARD( LONG, STRING ) 

LONG FUNCTION SMG$DELETE_VIRTUAL_KEYBOARD( LONG ) 

LONG FUNCTION SMG$READ_STRING( LONG, STRING, STRING, fc 
, LONG, LONG, STRING, LONG, LONG ) 


! + 

! Prompt the user for the timer value. A value of 0 will cause 
! the type ahead buffer to be read. 

i - 

INPUT "Enter timer value (0 to read typeahead buffer): TIMER 

! Tell SMG to use the timer value 
! - 

MODIFIER = IO$M_TIMED 


Establish a SMG connection to SYS$INPUT. Signal any unexpected 
errors. 


RET.STATUS * SMG$CREATE_VIRTUAL_KEYBOARD( KB.ID, "SYS$INPUT:" ) 
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IF (RET.STATUS AND 17.) = 07. THEN 
CALL LIB$SIGNAL( RET.STATUS ) 

END IF 

• + 

! Tell SMG to use any keystroke except a letter or number 
! as a terminator to the input and perform the read. 

! Signal any error except SS$_TIMEOUT 

TERM.SET = STRINGS( 47.. -17. ) + STRING$(127.. 07.) 

RET.STATUS = SMG$READ_STRING( KB_ID, DATA.STR, , , & 

MODIFIER, TIMER, TERM.SET, & 

STR.LEN, TERM.CODE ) 

IF (RET.STATUS <> SS$_TIMEOUT) AND ((RET.STATUS AND 17.) = 07.) THEN 
CALL LIB$SIGNAL( RET.STATUS ) 

END IF 

! + 

! All the data should come back as a terminator code, since any 
! character can be a terminator. 

i - 

PRINT "data string = ";LEFT(DATA.STR, STR.LEN) 

PRINT "term.code - TERM.CODE 
SELECT TERM.CODE 

CASE 0 TO 31 

PRINT "You typed a control character" 

CASE 32 TO 127 

PRINT "You typed: ";CHR$(TERM.CODE) 

CASE SMG$K_TRM_PF1 TO SMG$K_TRM_PERIOD 

PRINT "You typed one of the keypad keys" 

CASE SMGSK.TRM.UP TO SMG$K_TRM_RIGHT 

PRINT "You typed one of the cursor positioning keys" 

CASE SMG$K_TRM_F6 TO SMG$K_TRM_F20 

PRINT "You typed one of the function keys" 

CASE SMGSK.TRM.El TO SMG$K_TRM_E6 

PRINT "You typed one of the editing keys" 

CASE SMGSK.TRM.TIMEOUT 

PRINT "You did not type a key fast enough" 

CASE ELSE 

PRINT "I'm not sure what key you typed" 

END SELECT 
! + 

! Close the connection to SYS$INPUT, and signal any errors. 

i - 

RET.STATUS = SMG$DELETE_VIRTUAL_KEYBOARD( KB.ID ) 

IF (RET.STATUS AND 17.) = 07. THEN 
CALL LIB$SIGNAL( RET.STATUS ) 

END IF 

END 


This BASIC example program demonstrates the use of SMG$READ_STRING. 
One sample of the output generated by this program is as follows: 

Enter timer value (0 to read typeahead buffer): ? 5 

d 

data string = d 
term.code = 13 

You typed a control character 
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C This FORTRAN example program demonstrates how to use 
C SMGlREAD.STRING. 

C 

C This routine creates a virtual display and writes it to the pasteboard. 

C Data is placed in the virtual display via SMG$PUT_CHARS. 

C- 

C+ 

C Include the SMG definitions. In particular, we want SMG$M_BORDER. 

C- 

IMPLICIT INTEGER (A-Z) 

INCLUDE '($SMGDEF)' 

CHARACTER*20 TEXT 
C+ 

C Create a virtual display with a border using SMG$CREATE_VIRTUAL_DISPLAY. 
C- 

ROWS = 7 
COLUMNS = 50 

STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER) 

IF (.NOT. STATUS) CALL L IB$SI GNAL(y.VAL( STATUS)) 

C+ 

C Use SMG$CREATE_PASTEBOARD to create the pasteboard. 

C- 


STATUS * SMG$CREATE_PASTEBOARD (PASTED 
IF (.NOT. STATUS) CALL LIB$SIGNAL(7.VAL(STATUS)) 


C+ 

C Create a virtual keyboard by calling SMG$CREATE_VIRTUAL_KEYBOARD. 
C- 

STATUS = SMG$CREATE_VIRTUAL_KEYBOARD ( KEYBOARD1) 

IF (.NOT. STATUS) CALL L IB$S I GNAL(*/.VAL( STATUS)) 


C+ 

C Use SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display 
C at row 3, column 9. 

C- 


STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 3, 9) 
IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 


C+ 

C Read a string from the virtual pasteboard using SMG$READ_STRING. 
C- 


STATUS = SMG$READ_STRING ( KEYBOARD1, 

1 TEXT, 'prompt', 20. . DISPLAY1) 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 
END 


The output generated by this FORTRAN program before the call to 
SMG$READ_STRING is shown in Figure RTL-34. The program is waiting 
for input. The cursor immediately follows the word prompt. 
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Figure RTL-34 


Output Generated Before the Call to 
SMG$READ_STRING 


r 
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The output generated after the call to SMG$READ_STRING is shown in 
Figure RTL-35. 


Figure RTL-35 Output Generated After the Call to 
SMG$READ_ STRING 
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SMG$READ_VERIFY—Read and Verify a 

String 



SMG$READ_VERIFY reads a sequence of characters and verifies 
the sequence. 

FORMAT 

SMG$READ_VERIFY 

keyboard-id , out-string 
, in-string,pic-string 
, fill-char, dear-char 
[, prompt-string] [, modifiers] 

[, timeout] [, terminator-set] 

[, ini-offset] [, terminator-code] 

[, display-id] [,alt-echo-string] 

[, alt-display-id] [, rendition-set] 

[, rendition-complement] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

keyboard-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Keyboard identifier. The keyboard-id argument is the address of an unsigned 
longword integer containing the identifier of the virtual keyboard from which 
to read. The virtual keyboard is created by calling the SMG$CREATE_ 
VIRTUAL —KEYBOARD routine. 

out-string 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Output string into which SMG$READ_VERIFY writes the characters that are 
read. The out-string argument is the address of a descriptor pointing to this 
output string. 
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in-string 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Input string that contains the initial characters of the field. The in-string 
argument is the address of a descriptor pointing to the input string. 

pic-string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Picture string that contains a picture of what the field is to look like. The 
pic-string argument is the address of a descriptor pointing to the picture 
string. 

For more information on the legal values for the pic-string argument, see 
Section 8.4.1.4 in the VAX/VMS I/O User's Reference Manual: Part I. 


fill-char 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Fill character. The fill-char argument is the address of a descriptor pointing 
to the string that contains the character to be used as a fill character in the 
in-string argument. 

For more information on the fill-char parameter, see Section 8.4.1.4 in the 
VAX/VMS I/O User's Reference Manual: Part I. 

dear-char 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Clear character. The clear-char argument is the address of a descriptor 
pointing to the string that contains the character to be displayed for each 
occurrence of fill-char in in-string. 

For more information on the clear-char argument, see Section 8.4.1.4 in the 
VAX/VMS I/O User's Reference Manual: Part I. 

prompt-string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Prompt string. The prompt-string argument is the address of a descriptor 
pointing to the string that SMG$READ_VERIFY uses as the prompt for the 
read operation. This is an optional argument. 
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modifiers 


VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Modifiers. The modifiers argument is a longword bit mask that specifies 
optional behavior. The bits defined are the same as for the $QIO item-list 
entry TRM$_MODIFIERS. This is an optional argument. 


Valid modifiers are: 


• TRM$M_TM_CVTLOW 

• TRM$M_TM_NOECHO 

• TRM$M_TM—PURGE 

• TRM$M_TM_TRMNOECHO 

• TRM$M—TM_NOEDIT 

• TRM$M—TM_NORECALL 


See the terminal driver section of the VAX/VMS I/O User's Reference Manual: 
Part I for more information on modifiers. The TRM$ symbols are defined by 
the $TRMDEF macro/module in DIGITAL-supplied system symbol libraries. 


timeout 

VMS Usage: longword—signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Timeout count. The timeout argument is optional. If specified, all the 
characters typed in before the timeout are returned in the buffer. If omitted, 
characters are returned in the buffer until a terminator is seen. 


terminator-set 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor, fixed length 

Either a mask that specifies which characters are to be treated as terminators 
(short form) or a descriptor pointing to such a mask (long form). The 
terminator-set argument is the address of a descriptor pointing to the mask. 


If you want to use terminators with ASCII values in the range 0 to 31, use 
the short form. You create this mask by setting the bit that corresponds to 
the ASCII value of desired terminator. For example, to specify that CTRL/A 
(ASCII value 1) is a terminator, you set bit 1 in the terminator-set mask. 

If you want to use terminators with ASCII values outside the range 0 to 31, 
use the long form and create a descriptor of this form first: 


RTL-728 


April 1986 









Run-Time Library Routines 

SMG$READ_VERIFY 


31 16 15 0 


(not used) 

mask size in bytes 

address of mask 
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The mask itself has the same format as that of the short form; however, the 
long form allows use of a more comprehensive set of terminator characters. 
For example, a mask size of 16 bytes allows any 7-bit ASCII character to be 
set as a terminator, while a mask size of 32 bytes allows any 8-bit character to 
be set as a terminator. Any mask size between 1 and 32 bytes is acceptable. 

If the terminator mask is all zeros, there are no specified terminators and the 
read terminates when the number of characters specified in the max-length 
argument have been transferred. 

If the terminator-set argument is omitted, the set of terminators is the VMS 
default terminator set. For more information see the VAX/VMS I/O User's 
Reference Manual: Part 1, Section 8.4.1.2. 


ini-offset 

VMS Usage: longword—signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Input string offset. The ini-offset argument is a longword that contains 
the number of characters (from the in-string argument) to output after the 
prompt before waiting for input. 


terminator-code 


VMS Usage: 
type: 
access: 
mechanism: 


word-unsigned 
word (unsigned) 
write only 
by reference 


Key terminator code. The terminator-code argument is an unsigned word 
into which SMG$READ_VERIFY writes a code indicating what character or 
key terminated the read. Key terminator codes are of the form SMG$K_ 
TRM—keyname. The keynames are listed in Table RTL-1, in Chapter 3. 


display-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display identifier. The optional display-id argument is the address of an 
unsigned longword integer that contains the identifier of the virtual display 
in which the read is to be performed. If specified, SMG$READ—VERIFY 
begins the read at the current virtual cursor position in that virtual display. If 
omitted, the read begins in the current physical cursor position. Note that the 
length of the prompt-string plus the input is limited to the number of visible 
columns in the display. 
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alt-echo-string 


VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Alternate echo string. The alt-echo-string argument is a string that is printed 
after the first character is typed during the read operation. This is an optional 
argument. 


alt-display-id 

VMS Usage: longword_signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Alternate display identification. The alt-display-id is a signed longword 
integer containing the identification of the virtual display in which the alt- 
echo-string argument is to be printed. This is an optional argument. If 
specified, the output begins at the current virtual cursor position in that 
virtual display. If omitted, the value of the display-id argument is used as 
the default. If display-id is not specified, the output begins in the current 
physical cursor position. 


rendition-set 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Attribute specifier. The optional rendition-set argument is the address of a 
longword bit mask in which each 1-bit attribute causes the corresponding 
attribute to be set in the display. The following attributes can be specified 
using the rendition-set argument: 


SMG$M_BLINK 

SMG$M_BOLD 

SMG$M_RE VERSE 

SMG$M_UNDERLINE 


Displays characters blinking. 

Displays characters in higher-than-normal intensity 
(bolded). 

Displays characters in reverse video — that is, using the 
opposite default rendition of the virtual display. 

Displays characters underlined. 


The display-id argument must be specified when using the rendition-set 
argument. 


rendition-complement 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Attribute complement specifier. The optional rendition-complement 
argument is the address of a longword bit mask in which each 1-bit attribute 
causes the corresponding attribute to be complemented in the display. All 
of the attributes that can be specified with the rendition-set argument can 
be complemented with the rendition-complement argument. The display- 
id argument must be specified when using the rendition-complement 
argument. 
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DESCRIPTION This routine reads a sequence of characters from the virtual keyboard specified 

and verifies the sequence against the picture string. It then returns characters 
read to the caller. The caller may also specify that a code indicating the 
terminator be returned. 

The optional arguments rendition-set and rendition-complement let the 
user control the attributes of the virtual display in which the read is done. 
The rendition-set argument sets certain virtual display attributes, while 
rendition-complement complements these attributes. If the same bit is 
specified in both the rendition-set and rendition-complement parameters, 
the rendition-set is evaluated first, followed by rendition-complement. By 
using these two parameters together, the user can control each virtual display 
attribute in a single procedure call. On a single-attribute basis, the user can 
cause the following transformations: 


Set 

Complement 

Action 

0 

0 

Attribute unchanged. 

1 

0 

Attribute set to "on." 

0 

1 

Attribute set to complement of current setting. 

1 

1 

Attribute set to "off." 


For additional information on read-verify operations, see the VAX /VMS I/O 
User's Reference Manual: Part I. Note that display batching for both the 
pasteboard and the virtual display must be off when you use SMG$READ_ 
VERIFY. 


CONDITION 

VALUES 

RETURNED 


SSS—NORMAL 

SS$_CANCEL 

SS$_ABORT 


SMG$_DISREQ 


SMG$_EOF 

SMG$_INVDIS_ID 

SMG$_INVKBD_ID 

SMG$_LENNOTEQL 

SMG$_LENMUSONE 

SMG$_WRONUMARG 

LIB$__xxx 

RMS$_xxx 

SS$_xxx 


Normal successful completion. 

I/O operation canceled while queued (by 
SMG$CANCEL _JNPUT). 

I/O operation aborted during execution (by 
SMG$CANCEI_INPUT). 

A call to SMG$READ_VERIFY was made 
specifying right-justification; no display-id 
was specified; and the SCROLL—REVERSE 
sequence was not found for this terminal in 
TERMTABLE.EXE. Add the display-id argument to 
the SMGSREAD_VERIFY call or add the SCROLL- 
REVERSE sequence to TERMTABLE.EXE. 

End-of-file. 

Invalid display-id. 

Invalid keyboard-id. 

Length of pic-string and in-string are not equal. 
Length of fill-char and clear-char must be 1. 
Wrong number of arguments. 

Any error from LIB$SCOPY_R_DX. 

Any error from $GET (except RMS$_EOF). 

Any error from $QIOW. 
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SMG$REPAINT_LIIME 

Repaint One or More Lines on the Current 
Screen 



SMG$REPAINT_LINE repaints a series of lines on the current screen. 

FORMAT 

SMG$REPAINT_LINE pasteboard-id,row-start 

[,num-of-lines] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Pasteboard identifier. The pasteboard-id argument is the address of the 
pasteboard associated with the physical screen to be repainted. 

row-start 

VMS Usage: longword—signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Starting row number. The row-start argument is the address of the physical 
row number to start repainting. 

num-of-lines 

VMS Usage: longword—signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Number of contiguous lines to repaint. The num-of-lines argument is the 
address of a signed longword containing the number of lines. This argument 
is optional. If not specified, the default is 1. 

DESCRIPTION 

SMG$REPAINT_LINE repaints a line or series of lines on the current screen 
based on its internal knowledge of what the screen should look like. You 
should call SMG$REPAINT_LINE when you suspect that the screen has been 
disrupted. 
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If pasteboard batching is in effect, the repaint occurs from the screen image; 
otherwise, it occurs from the text image. SMG$REPAINT_LINE has the 
added benefit of circumventing the restriction that the display you are 
working on must be pasted to column one. (For further information on 
this restriction, refer to the description section of SMG$READ_STRING.) 

This routine should not be used if the line being repainted is double high. 

One good use of SMG$REPAINT_LINE is to restore a line after entering a 
CTRL/U or CTRL/R to an input routine. 


CONDITION 

VALUES 

SIGNALED 


SS$NORMAL 

SMG$_INVPAS_ID 


Normal successful completion. 
Invalid pasteboard control block. 
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SMG$REPAINT_SCREEN—Repaint Current 

Screen 


SMG$REPAINT_SCREEN repaints the current screen after nonSMG 
I/O has occurred. 

FORMAT 

SMG$REPAINT_SCREEN pasteboard-id 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

pasteboard-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the terminal screen to be repainted. The pasteboard-id argument is 
the address of an unsigned longword that contains the pasteboard identifier. 

DESCRIPTION 

SMG$REPAINT_SCREEN repaints the current screen. It is intended to 
be used when some outside agent (for example, a broadcast message) has 
disrupted the screen. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_INVPAS_ID Invalid pasteboard-id. 

SMG$_WRONUMARG Wrong number of arguments. 

EXAMPLE 


C+ 

C This FORTRAN example program demonstrates 
C the use of SMG$REPAINT_SCREEN. 

C- 

IMPLICIT INTEGER (A-Z) 

C+ 

C Create the virtual display by calling 
C SMG$CREATE_VIRTUAL_DISPLAY. To create 
C a border, we set BORDER = 1. No border 
C would be BORDER * 0. 

C- 

INCLUDE *($SMGDEF)' 

ROWS * 3 
COLUMNS = 50 
BORDER = 1 

STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
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1 (ROWS, COLUMNS, DISPLAY1, BORDER) 

IF (.NOT. STATUS) CALL LIB$SIGNAL('/.VAL(STATUS)) 

C+ 

C Create the pasteboard using SMG$CREATE_PASTEBOARD. 

C- 

STATUS = SMG$CREATE_PASTEBOARD (PASTED 
IF (.NOT. STATUS) CALL LIB$SIGNAL C/.VAL (STATUS) ) 

C+ 

C Put data in the virtual display by calling SMG$PUT_CHARS. 

C- 

STATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This virtual display has 3 rows and 50 columns.', 1, 1) 

IF (.NOT. STATUS) CALL LIB$S IGNALC/.VAL ( STATUS ) ) 

STATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This is a bordered virtual display.', 2, 1) 

IF (.NOT. STATUS) CALL LIB$SIGNAL ('/, VAL (STATUS) ) 

STATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' SMG$PUT_CHARS puts data in this virtual display.', 3, 1) 

IF (.NOT. STATUS) CALL LIB$SIGNAL('/.VAL(STATUS)) 

C+ 

C Call SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display. 

C- 

STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1. PASTE1, 4, 15) 

IF (.NOT. STATUS) CALL LIBlSIGNALC/.VAL(STATUS)) 

C+ 

C Mess up the screen with some FORTRAN output. 

C- 

WRITE (6,*) 'Mess up the screen.' 

WRITE (6,*) 'More mess.' 

C+ 

C Call SMG$REPAINT_SCREEN to repaint the screen. 

C- 

STATUS = SMG$REPAINT_SCREEN ( PASTED 
IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 

END 


The output generated by this FORTRAN program before the call to 
SMG$REPAINT_SCREEN is shown in Figure RTL-36. 
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Figure RTL-36 


Output Generated by FORTRAN Program Calling 
SMG$REPAINT_SCREEN 



The output generated after the call to SMG$REPAINT_SCREEN is shown in 
Figure RTL-37. 

Figure RTL-37 Output Generated by FORTRAN Program Calling 
SMG$REPAINT_SCREEN 
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SMG$REPASTE_VIRTUA1_DISPLAY 

Repaste Virtual Display 



SMG$REPASTE_VIRTUAI_DISPLAY moves a virtual display to a 

new position on the pasteboard. The pasting order is not preserved. 

FORMAT 

SMG$REPASTE_VIRTUAI_DISPLAY 

display-id ,pasteboard-id ,pb-row 
,pb-column [, top-display-id] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display to be repasted. The display-id argument is the 
address of an unsigned longword that contains the display identifier. 

Display-id is returned by SMG$CREATE-VIRTUAL-DISPLAY. 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard on which the display is repasted. The pasteboard-id 
argument is the address of an unsigned longword that contains the pasteboard 
identifier. 

pb-row 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the pasteboard row that is to contain row 1 of the specified virtual 
display. The pb-row argument is the address of a signed longword integer 
that contains the pasteboard row. 
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pb-column 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the pasteboard column that is to contain column 1 of the specified 
virtual display. The pb-column argument is the address of a signed longword 
integer that contains the pasteboard column. 

top-display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Optional identifier of the virtual display under which display-id will be 
pasted. The top-display-id argument is the address of an unsigned longword 
containing the identifier of this virtual display. Note that the virtual display 
specified by top-display-id must already be pasted. 

DESCRIPTION 

SMG$REPASTE_VIRTUAL—DISPLAY lets you move a virtual display to 
a new position on its pasteboard. This routine calls SMG$UNPASTE_ 
VIRTUAL-DISPLAY and SMG$PASTE-VIRTUAL-DISPLAY. Note that this 
changes the pasting order. The unpasting and repasting operations use the 
SMG$BEGIN —PASTEBOARD—UPDATE and SMG$END_PASTEBOARD- 
UPDATE; thus, there is no effect on the screen until the repasting operation is 
complete. 

Note that this routine may cause the virtual display to be at the top of 
the pasting order. To move a virtual display without changing its pasting 
order, use SMG$MOVE_VIRTUAL—DISPLAY. If the optional argument 
top-display-id is specified, SMG$REPASTE_VIRTUAL— DISPLAY pastes 
the virtual display being repasted under the virtual display specified by top- 
display-id. In this case, the virtual display specified by top-display-id must 
already be pasted. 

CONDITION 

VALUES 

RETURNED 

SSS—NORMAL Normal successful completion. 

SMG$_INVDIS_ID Invalid display-id. 

SMG$_INVPAS—ID Invalid pasteboard-id. 

SMG$_WRONUMARG Wrong number of arguments. 


EXAMPLE 

C+ 

C This FORTRAN example program demosntrates the use of 
C SMG$REPASTE_VIRTUAL_DISPLAY and SMG$MOVE_VIRTUAL_DISPLAY. 
C- 

IMPLICIT INTEGER (A-Z) 

C+ 


Include the SMG definitions. In particular, we want SMG$M_BORDER 
INCLUDE '($SMGDEF)' 


C+ 

C Create a virtual display with a border by calling 
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C SMG$CREATE_VIRTUAL_DISPLAY. 

C- 

ROWS = 3 
COLUMNS = 50 

STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
1 (ROWS. COLUMNS, DISPLAY1, SMG$M_BORDER) 

IF (.NOT. STATUS) CALL LIB$SIGNAL C/.VAL (STATUS)) 

C+ 

C Call SMG$CREATE_PASTEBOARD to create the pasteboard. 

C- 

STATUS = SMG$CREATE_PASTEBOARD (PASTED 
IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 

C+ 

C Put data in the virtual display using SMG$PUT_CHARS. 

C- 

STATUS = SMG$PUT_CHARS ( DISPLAY1. 

1 ' This virtual display has 3 rows and 50 columns.', 1, 1) 

IF (.NOT. STATUS) CALL LIB$SIGNAL C/.VAL (STATUS)) 

STATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' This is a bordered virtual display.', 2, 1) 

IF (.NOT. STATUS) CALL LIB$SIGNAL C/.VAL (STATUS)) 

STATUS = SMG$PUT_CHARS ( DISPLAY1, 

1 ' SMG$PUT_CHARS puts data in this virtual display.', 3, 1) 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 

C+ 

C Call SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display. 

C- 

STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15) 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 

C+ 

C Move the virtual display by calling SMG$MOVE_VIRTUAL_DISPLAY. 

C- 

STATUS = SMG$MOVE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 10, 5) 

IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 

C+ 

C Call SMG$REPASTE_VIRTUAL_DISPLAY to repaste the 
C original virtual display as it was. 

C- 

STATUS = SMG$REPASTE_VIRTUAL_DISPLAY (DISPLAY1, PASTE1, 4, 15) 
IF (.NOT. STATUS) CALL LIB$SIGNALC/.VAL(STATUS)) 

END 


The output generated by this FORTRAN program before the call to 
SMG$MOVE_VIRTUAL—DISPLAY is shown in Figure RTL-38. 
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Figure RTL-38 


Output before the Call to SMG$MOVE_ 
VIRTUAL-DISPLAY 



After the call to SMG$MOVE —VIRTUAL —DISPLAY, the output shown is 
that illustrated in Figure RTL-39. 

Figure RTL-39 Output Displayed After the Call to SMG$MOVE_ 
VIRTUAL-DISPLAY 
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Figure RTL-40 shows the final output displayed, after the call to 
SMG$REPASTE—VIRTUAL—DISPLAY. 

Figure RTL-40 Output Displayed After the Call to 

SMG$REPASTE_VIRTU Al_DISPLAY 
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SMG$REPLACE_INPUT-LINE—Replace 

Input Line 



SMG$REPLACE_INPUT_LINE replaces the specified lines in the 
recall buffer with the specified string. 

FORMAT 

SMG$REPLACE_INPUT_LINE keyboard-id 

[, out-line] 
[,num-of-lines] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

keyboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Keyboard identifier. The keyboard-id argument is the address of an unsigned 
longword containing the identifier of the virtual keyboard from which to read. 
The virtual keyboard is created by calling the SMG$CREATE —VIRTUAL — 
KEYBOARD routine. 

out-line 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String that contains the line to be entered into the recall buffer. The out-line 
argument is the address of a descriptor pointing to this string. The default is 
a null string, which removes the last line entered. 

num-of-lines 

VMS Usage: byte_unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by reference 

Number of lines to be replaced. The num-of-lines argument is the address of 
an unsigned byte containing the number of lines to be replaced with out-line. 
The default value for the num-of-lines argument is 1 (the last line entered). 

DESCRIPTION 

SMG$REPLACE_INPUT_LINE replaces the requested lines in the recall 
buffer with the specified string. The remaining (num-of-lines - 1) lines are 
deleted. This routine is intended to aid in processing line continuations. 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL Normal successful completion. 

SMG$_INVKBD_ID Invalid keyboard-id. 

SMG$_WRONUMARG Wrong number of arguments. 

LIB$_INSVIRMEM Insufficient virtual memory. 
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SMG$RESTORE_PHYSICAL-SCREEN 
Restore Physical Screen 



SMG$RESTORE_PHYSICAL_SCREEN rewrites the screen image 

as it was at the time the SMG$SAVE_PHYSICAI_SCREEN routine 

was called. 

FORMAT 

SMG$RESTORE_PHYSICAI_SCREEN 

pasteboard-id, saved-display-id 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the physical screen to be restored. The pasteboard-id argument is 
the address of an unsigned longword that contains the pasteboard identifier. 

Pasteboard-id is returned by the SMG$CREATE —PASTEBOARD routine. 

saved-display-id 

VMS Usage, longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display created by the SMG$SAVE—PHYSICAL _ 
SCREEN routine. The saved-display-id argument is the address of an 
unsigned longword that contains this display identifier. 

DESCRIPTION 

SMG$RESTORE_PHYSICAL—SCREEN reproduces the screen image saved 
by the SMG$SAVE—PHYSICAL— SCREEN routine. You must pass the 
display-id returned by the SMG$SAVE_PHYSICAL—SCREEN routine to the 
SMG$RESTORE_PHYSICAL—SCREEN routine. Note that when performing 
multiple calls to SMG$SAVE-PHYSICAL-SCREEN and SMG$RESTORE_ 
PHYSICAL—SCREEN, the calls must be performed in a nested fashion; that 
is, the last screen saved must be the first one restored. 
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SSS—NORMAL Normal successful completion. 

SMG$_INVDIS_ID Invalid display-id. 

SMG$_INVPAS_ID Invalid pasteboard-id. 
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SMG$RETURN_CURSOR_POS—Return 

Cursor 

Position 



SMG$RETURN_CURSOR_POS returns the current virtual cursor 
position in a specified virtual display. 

FORMAT 

SMG$RETURN_CURSOR_POS display-id 

, row-number 
, column-number 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display whose current cursor position you are requesting. 
The display-id argument is the address of an unsigned longword that 
contains the display identifier. Display-id is returned by SMG$CREATE_ 
VIRTUAL-DISPLAY. 

row-number 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Receives the cursor's current row position within the specified virtual display. 
The row-number argument is the address of a longword into which is written 
the current row position. 

column-number 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Receives the cursor's current column position within the specified virtual 
display. The column-number argument is the address of a longword into 
which is written the current column position. 

DESCRIPTION 

SMG$RETURN_CURSOR—POS returns the virtual cursor's current row and 
column positions in a specified virtual display. 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL Normal successful completion. 

SMG$_INVDIS_ID Invalid display-id. 

SMG$_WRONUMARG Wrong number of arguments. 
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SMG$RETURN_INPUT_LINE—Return Input 

Line 

SMG$RETURN_INPUT_LINE returns to the caller the requested line 
from the recall buffer. This line is retrieved either by matching it with 
a specified string or by specifying the appropriate line number. 

FORMAT 

SMG$RETURN_INPUT_LINE 

keyboard-id, out-line 

[,match-string] 

[,line-num] 

[ r out-length] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 

keyboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 



Keyboard identifier. The keyboard-id argument is the address of an unsigned 
longword containing the identifier of the virtual keyboard from which to read. 
The virtual keyboard is created by calling the SMG$CREATE—VIRTUAL _ 
KEYBOARD routine. 


out-line 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

String into which is written the complete recalled line. The out-line argument 
is the address of a descriptor pointing to this string. 


match-string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Match string to be used when searching for the line to be recalled. The 
optional match-string argument is the address of a descriptor pointing to this 
match string. The search begins with the last line typed. 
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line-num 

VMS Usage: byte_unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by reference 

Line number to be used when searching for the line to be recalled. The 
optional line-num argument is the address of an unsigned byte containing 
the number of the line to be recalled. The last line typed is line number 1. 

out-length 

VMS Usage: word—unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Length of the out-line string. The optional out-length argument is the 
address of an unsigned word containing either the number of characters read 
or the maximum length of out-line, whichever is less. 

DESCRIPTION 

SMG$RETURN_INPUT_LINE returns to the caller the specified line in the 
recall buffer. If the match-string argument is specified, SMG$RETURN_ 
INPUT-LINE searches for and returns the line that matches the specified 
string. If the line-num argument is specified, SMG$RETURN—INPUT—LINE 
returns the line that corresponds to the specified line number. This routine is 
intended to aid in the implementation of a DCL style "RECALL" command. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_INVKBD_ID Invalid keyboard-id. 

SMG$_WRONUMARG Wrong number of arguments. 

LIB$_xxx Any error from LIB$COPY_R_DX. 
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SMG$RING_BELL 


SMG$RIIMG_BELL—Ring the Terminal Bell 



or Buzzer 

SMG$RING_BELL sounds the terminal bell or buzzer. 

FORMAT 

SMG$RING_BELL display-id[,number-of-times] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display for which the bell or buzzer sounds. The display- 
id argument is the address of an unsigned longword that contains the display 
identifier. 

Display-id is returned by SMG$CREATE-VIRTUAL-DISPLAY. 

number-of-times 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the number of times the bell or buzzer is sounded. The number-of- 
times argument is the address of a signed longword integer that contains the 
number of times the bell or buzzer is sounded. If omitted, 1 is used. 

DESCRIPTION 

SMG$RING_BELL sounds the bell or buzzer on each pasteboard (terminal) 
to which the specified virtual display is pasted. The bell or buzzer sounds the 
number of times specified; the default number of times is 1. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_INVDIS_ID Invalid display-id. 

Any condition values returned by $QIOW. 

Any condition values returned by STR$DUPL_CHAR. 
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SMG$SAVE_PHYSICAI_SCREEN 


SMG$S A VE-PHYSICAL-SCREEN 

Save Physical Screen 


SMG$SAVE_PHYSICAI_SCREEN saves the contents of the screen 

so that a later call to SMG$RESTORE_PHYSICAI_SCREEN can 

restore it. 

FORMAT 

SMG$SAVE_PHYSICAI_SCREEN 

pasteboard-id, saved-display-id 
[, desired-row-start] 

[, desired-ro w-end] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the physical screen whose contents are to be saved. The 
pasteboard-id argument is the address of an unsigned longword that contains 
the pasteboard identifier. 

saved-display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Receives the display id of the display created to contain the contents of 
the physical screen. The saved-display-id argument is the address of an 
unsigned longword into which the display identifier is written. 

Saved-display-id must be passed to the SMG$RESTORE —PHYSICAL _ 
SCREEN routine to restore the saved information. 

desired-row-start 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the first row to be saved. The desired-row-start argument is the 
address of a signed longword integer that contains the row number. If 
omitted, row 1 of the pasteboard is used. 
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SMG$SAVE_PHYSICAI_SCREEN 



desired-row-end 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the last row to be saved. The desired-row-end argument is the 
address of a signed longword integer that contains the row number. If 
omitted, the last row of the pasteboard is used. 

DESCRIPTION 

SMG$SAVE—PHYSICAL—SCREEN blanks the screen by creating a virtual 
display that is as wide as the physical screen and as high as specified by the 
desired-row-start and desired-row-end arguments. If these two arguments 
are omitted, the created virtual display is as high as the physical screen. The 
information saved — that is, the screen image — can be restored by calling 
the SMG$RESTORE-PHYSICAL-SCREEN routine. When performing 
multiple calls to SMG$SAVE-PHYSICAL-SCREEN and SMG$RESTORE— 
PHYSICAL—SCREEN, the calls must be performed in a nested order; that is, 
the last screen saved must be the first one restored, and so on. 

These routines are useful when calling a procedure that may send output 
to the screen without using the Screen Management Facility. Before calling 
such a procedure, you save the screen image with SMG$SAVE—PHYSICAL _ 
SCREEN. After the procedure executes, you restore the screen image with 
SMG$RESTORE -PHYSICAL -SCREEN. 

Note that when using SMG$SAVE_PHYSICAL— SCREEN on a terminal 
that does not support scrolling regions, you must save and restore the entire 
screen. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_INVPAS_ID Invalid pasteboard-id. 

SMG$_WRONUMARG Wrong number of arguments. 

LIB$_INSVIRMEM Insufficient virtual memory. 
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SMG$SCROLL_DISPLAY_AREA 


SMG$SCROLL -DISPLAY-AREA—Scroll 

Display 

Area 



SMG$SCROLI—DISPLAY-AREA scrolls a rectangular region of a 
virtual display. 

FORMAT 

SMG$SCROLI_DISPLAY_AREA display-id 

[, starting-row 
, starting-column] 
[, height] [, width] 

[, direct ion] 

[, count] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display in which scrolling takes place. The display-id 
argument is the address of an unsigned longword that contains the display 
identifier. 

Display-id is returned by SMG$CREATE-VIRTUAL-DISPLAY. 

starting-row 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the first row of the scrolling region. The starting-row argument is 
the address of a signed longword integer that contains the starting row. 

If omitted, row 1 of the specified virtual display is used. Note that if you omit 
either starting-row or starting-column, the default (row 1 and column 1) is 
used. 
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SMG$SCROLL_ 

_DISPLAY_AREA 


starting-column 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the first column of the scrolling region. The starting-column 
argument is the address of a signed longword integer that contains the 
starting column. 

If omitted, column 1 of the specified virtual display is used. Note that if you 
omit either starting-row or starting-column, the default (row 1 and column 

1) is used. 

height 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the number of rows in the scrolling region. The height argument is 
the address of a signed longword integer that contains the number of rows. 

If omitted, this value defaults to either the height of the scrolling region (if 
one has been explicitly set with SMG$SET_DISPLAY_SCROLL—REGION) or 
the height of the specified virtual display. 

width 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the number of columns in the scrolling region. The width argument 
is the address of a signed longword integer that contains the number of 
columns. 

If omitted, this value defaults to either the width of the scrolling region (if 
one has been explicitly set with SMG$SET_DISPLAY—SCROLL—REGION) or 
the width of the specified virtual display. 

direction 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the direction to scroll. The direction argument is the address of an 
unsigned longword that contains the direction code. 

Valid values are SMG$M_UP, SMG$M_DOWN, SMG$M—RIGHT and 
SMG$M_LEFT. SMG$M_UP is the default. 
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SMG$SCROLI_DISPLAY-AREA 



count 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the number of lines to scroll. The count argument is the address 
of a signed longword integer that contains the number of lines to scroll. If 
omitted, one line is scrolled. 

DESCRIPTION 

SMG$SCROLL_DISPLAY_AREA scrolls a rectangular region of the specified 
virtual display. It scrolls the region a specified number of lines in the specified 
direction. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_INVDIS_ID Invalid display-id. 

SMG$_INVCOL Invalid column. 

SMG$_INVROW Invalid row. 

SMG$_WRONUMARG Wrong number of arguments. 
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SMG$SET_BROADCAST_TRAPPING 


SMG$SET_BROADCAST_TRAPPING 
Enable Broadcast Trapping 



SMG$SET_BROADCAST_TRAPPING enables the trapping of 
broadcast messages. 

FORMAT 

SMG$SET_BROADCAST_TRAPPING 

pasteboard-id [, AST-routine] 
[,AST-argument] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard for the terminal to be affected. The pasteboard-id 
argument is the address of an unsigned longword that contains the pasteboard 
identifier. 

Pasteboard-id is returned by SMG$CREATE—PASTEBOARD. 

AST-routine 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: read only 

mechanism: by reference 

The address of an AST routine to be called when a message is received at 
the terminal. The AST-routine argument is the address of the routine's 
procedure entry mask — that is, the address of the routine itself. 

When the AST-routine argument is either omitted or is given a value of 
zero, the BROADCAST mode is set to synchronize. In this mode, you must 
periodically call SMG$GET_BROADCAST—MESSAGE to see if any broadcast 
messages have arrived. 

AST-argument 

VMS Usage: user—arg 
type: longword (unsigned) 

access: read only 

mechanism: by value 

A value to be passed to the AST routine. AST-argument is the value to be 
passed to the AST routine. 
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SMG$SET_BROADCAST_TRAPPING 


DESCRIPTION SMG$SET_BROADCAST_TRAPPING enables the trapping of broadcast 

messages sent to the specified pasteboard (terminal). If you enable broadcast 
trapping with SMG$SET_BROADCAST—TRAPPING but do not disable it 
with SMG$DIS ABLE-BROADCAST-TRAPPING before the image exits, any 
messages that have been broadcast to the terminal are lost when the image 
exits. 

The AST routine is called with 5 parameters: AST-argument, RO, Rl, PC, 
and PSL. 



ZK-4803-85 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_INVPAS_ID 

SMG$_WRONUMARG 

SMG$_NOT_A_TRM 


Normal successful completion. 

Invalid pasteboard-id. 

Wrong number of arguments. 

Informational message. The pasteboard is not a 
terminal. 


Any condition values returned by $DASSGN or $CANCEL. 
Any condition values returned by LIB$ASN_WTH_MBX. 


EXAMPLE 


For an example of using SMG$SET_BROADCAST__TRAPPING, see the 
example for the routine SMG$DISABLE_BROADCAST_TRAPPING. 
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SMG$SET_CURSOR_ABS 


SMG$SET_CURSOR_ABS—Set Absolute 

Cursor 

Position 



SMG$SET_CURSOR_ABS moves the virtual cursor to the specified 
position in a virtual display. 

FORMAT 

S M G$SET_C U RSOR_ABS display-id[,row] 

[, column] 


RETURNS VMS Usage: cond_value 

type: longword (unsigned) 

access: write only 



mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display in which to set the virtual cursor position. The 
display-id argument is the address of an unsigned longword that contains 
the display identifier. 

Display-id is returned by SMG$CREATE—VIRTUAL —DISPLAY. 

row 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the row position to which the virtual cursor moves. The row 
argument is the address of a signed longword integer that contains the row 
number. If omitted, the cursor remains at the current row. 

column 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the column position to which the virtual cursor moves. The column 
argument is the address of a signed longword integer that contains the 
column number. If omitted, the virtual cursor remains at the current column. 

DESCRIPTION 

SMG$SET_CURSOR—ABS moves the virtual cursor to the specified position 
in the specified virtual display. 
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SMG$SET_CURSOR_ABS 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_INVDIS_ID 

SMG$_INVCOL 

SMG$_INVROW 

SMG$_WRONUMARG 


Normal successful completion. 
Invalid display-id. 

Invalid column. 

Invalid row. 

Wrong number of arguments. 
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SMG$SET_CURSOR_MODE 


SMG$SET_CURSOR_MODE 
Turn the Physical Cursor On or Off 



SMG$SET_CURSOR_MODE turns the physical cursor on or off. 

FORMAT 

SMG$SET_CURSOR_MODE pasteboard-id 

,cursor-mode 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

pasteboard-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Pasteboard identifier. The pasteboard-id argument is the address of an 
unsigned longword that contains the pasteboard identifier. 

cursor-mode 

VMS Usage: boolean 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Longword that determines whether or not the physical cursor is displayed. 
The cursor-mode argument is the address of an unsigned longword that 
determines the status of the physical cursor: if cursor-mode is zero, the 
physical cursor is displayed; if cursor-mode is set to 1, the physical cursor is 
invisible. 

DESCRIPTION 

SMG$SET_CURSOR__MODE turns the cursor on and off. The cursor is 
displayed if the cursor-mode argument is zero. If the cursor-mode argument 
is set to 1, the cursor is invisible. If your terminal does not have this 
capability defined, this routine has no effect. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_WRONUMARG Wrong number of arguments. 

SMG$_INVPAS_ID Invalid pasteboard-id. 

SMG$_INVARG Invalid argument. 
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SMG$SET_CURSOR_REL 


SMG$SET_CURSOR_REL—Move Cursor 
Relative To Current Position 



SMG$SET_CURSOR_REL moves the virtual cursor the specified 
number of rows and columns from the current virtual cursor position 
in a virtual display. 

FORMAT 

SMG$SET_CURSOR_REL display-id[,delta-row] 

[, delta-column] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display in which to move the virtual cursor. The display- 
id argument is the address of an unsigned longword that contains the display 
identifier. 

Display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY. 

delta-row 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the number of rows to move the virtual cursor. The delta-row 
argument is the address of a signed longword integer that contains the 
number of rows to move. If omitted, the virtual cursor remains at the current 
row position. If delta-row is positive, the virtual cursor moves downward the 
specified number of rows. If delta-row is negative, the virtual cursor moves 
upward the specified number of rows. 

delta-column 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the number of columns to move the cursor. The delta-column 
argument is the address of a longword that contains the number of columns 
to move. If omitted, the virtual cursor remains at the current column position. 
If delta-column is positive, the virtual cursor moves the specified number of 
columns to the right. If delta-column is negative, the virtual cursor moves 
the specified number of columns to the left. 
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SMG$SET_CURSOR_REL 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


SMG$SET_CURSOR_REL moves the virtual cursor the specified number 
of rows and columns relative to the current virtual cursor position. If the 
specified delta-row or delta-column causes the cursor to move outside 
the bounds of the virtual display, SMG$_INVROW or SMG$_INVCOL is 
returned. 


SS$_NORMAL 

SMG$_INVDIS_ID 

SMGS—INVARG 

SMG$_INVCOL 

SMG$_INVROW 

SMG$_WRONUMARG 



Normal successful completion. 

Invalid display-id. 

Invalid argument. 

An invalid value of delta-column caused the cursor 
to move outside the bounds of the virtual display. 

An invalid value of delta-row caused the cursor to 
move outside the bounds of the virtual display. 

Wrong number of arguments. 
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SMG$SET_DEFAULT_STATE 


SMG$SET_DEFAULT_STATE—Set 

Default 

State 

SMG$SET_DEFAULT_STATE sets and/or returns the current 
default state for a key table. 


FORMAT SMG$SET_DEFAULT_STATE key-table-id 

[, new-state] 
[, old-state] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


ARGUMENTS key-table-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read-only 

mechanism: by reference 

Specifies the key table in which you are setting or inquiring about a default 
state. The key-table-id argument is the address of an unsigned longword 
that contains the key table identifier. 

Key-table-id is returned by the SMG$CREATE_KEY_TABLE routine. 


new-state 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Specifies the new default state for the entire key table. The new-state 
argument is the address of a descriptor pointing to the new state string. The 
specified state name is converted to uppercase and stripped of trailing blanks 
before use. 


old-state 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Receives the existing default state name of the specified key definition table. 
The old-state argument is the address of a descriptor pointing to the storage 
into which the old state string is written. 
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SMG$SET_DEFAULT_STATE 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


SMG$SET_DEFAULT_STATE sets and/or returns the default state name for 
an entire key definition table. By changing the default state for an entire key 
definition table, you can use the keypad keys for a new set of functions. 


SSS—NORMAL 
SMG$_INVKTB_ID 
SMG$_IN VST AN AM 
LIB$_INVSTRDES 


Normal successful completion. 
Invalid key-table-id. 

Invalid state name. 

Invalid string descriptor. 
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SMG$SET_DISPLAY_SCROLI—REGION 


SMG$SET_DISPLAY_SCROLI—REGION 
Create Display Scrolling Region 

SMG$SET_DISPLAY_SCROLI_REGION creates a scrolling region in 

a virtual display. 


FORMAT SMG$SET_DISPLAY_SCROLI_REGION 

display-id [, starting-line] [, ending-line] 


RETURNS 

VMS Usage: 

cond_value 

type: 

longword (unsigned) 


access: 

write only 


mechanism: 

by value 


ARGUMENTS display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display in which scrolling takes place. The display-id 
argument is the address of an unsigned longword that contains the display 
identifier. 


Display-id is returned by SMG$CREATE—VIRTUAL —DISPLAY. 


starting-line 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the first line of the scrolling region. The starting-line argument 
is the address of a signed longword integer that contains the starting line 
number. If omitted, the first line of the display is used. 


ending-line 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Specifies the last line of the scrolling region. The ending-line argument is the 
address of a signed longword integer that contains the ending line number. If 
omitted, the last line of the virtual display is used. 
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SMG$SET_DISPLAY_SCROLI_REGION 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


SMG$SET_DISPLAY_SCROLL—REGION creates a logical scrolling region 
in a specified virtual display, using the specified starting and ending lines. If 
the starting-line and ending-line arguments are omitted, the entire display 
becomes a scrolling region. This routine does not change the appearance of 
the screen or the cursor position. 


SSS—NORMAL 

SMG$_INVDIS_ID 

SMG$_INVARG 

SMG$_INVROW 

SMG$_WRONUMARG 


Normal successful completion. 

Invalid display-id. 

Ending-line is less than or equal to starting-line. 
Invalid row. 

Wrong number of arguments. 
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SMG$SET_KEYPAD_MODE 


SMG$SET_KEYPAD_MODE—Set Keypad 

Mode 



SMG$SET_KEYPAD_MODE sets the terminal's numeric keypad to 
either numeric or applications mode. 

FORMAT 

SMG$SET_KEYPAD_MODE 

keyboard-id, new-mode 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

keyboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual keyboard whose mode is to be changed. The keyboard- 
id argument is the address of an unsigned longword that contains the 
keyboard identifier. 

Keyboard-id is returned by SMG$CREATE-VIRTUAL-KEYBOARD. 

new-mode 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies whether the keypad is to be in applications or numeric mode. The 
new-mode argument is the address of an unsigned longword that contains 
the new mode setting. If the low-order bit is clear, the keypad is set to 
numeric mode; if the low-order bit is set, the keypad is set to applications 
mode. All other bits must be zero. 

DESCRIPTION 

SMG$SET_KEYPAD—MODE sets the terminal's numeric keypad to either 
numeric or applications mode. In applications mode, numeric keypad keys 
are considered function keys and may be used as terminators. In numeric 
mode, these keys are equivalent to the corresponding keys on the main 
keyboard. 

To enable a successful call to SMG$SET_KEYPAD—MODE, the terminal must 
support applications mode. 
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SMG$SET_KEYPAD_MODE 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SMG$_WRONUMARG 

SMG$_INVKBD_ID 


Normal successful completion. 
Wrong number of arguments. 
Invalid keyboard-id. 
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SMG$SET_OUT_OF_BAND_ASTS 


SMG$SET_OUT_OF—BAND—ASTS 
Set Out-of-Band ASTs 



SMG$SET_OUT_OF_BAND_ASTS either enables or disables the 
trapping of out-of-band characters. 

FORMAT 

SMG$SET_OUT_OF_BAND_ASTS 

pasteboard-id , control-char-mask 
, AST-routine [,AST-argument] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

pasteboard-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the terminal for which out-of-band characters are enabled or 
disabled. The pasteboard-id argument is the address of an unsigned 
longword that contains the pasteboard identifier. Pasteboard-id is returned 
by SMG$CREATE—PASTEBOARD. 

control-char-mask 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies which control characters are to be the new out-of-band control 
characters. The control-char-mask argument is the address of an unsigned 
longword that contains the mask. You create this mask by setting the bit 
that corresponds to the ASCII value of the desired character. For example, to 
specify that CTRL/A (ASCII value 1) is an out-of-band control character, you 
set bit 1 in the control-char-mask. If no bits are set in this mask, then no 
out-of-band ASTs occur. For more information see the VAX/VMS I/O User's 
Reference Manual: Part /, Section 8.4.3.5. 

AST-routine 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: read only 

mechanism: by reference 

The address of an AST routine to be called when an out-of-band control 
character is typed at the terminal. The AST-routine argument is the address 
of the routine's procedure entry mask — that is, the address of the routine 
itself. 
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SMG$SET_OUT_OF_BAND_ASTS 


AST-argument 

VMS Usage: user_arg 
type: longword (unsigned) 

access: read only 

mechanism: by value 

The argument you supply for the AST. The AST-argument argument is 
an unsigned longword that contains the value to be passed to the AST 
routine. However, the AST routine may also need to know the out-of-band 
character and the pasteboard-id at which it was typed. Therefore, the Screen 
Management Facility creates a 3-longword structure to hold this information 
and passes the address of this structure as the first argument to the AST 
routine. The remaining four arguments are RO, Rl, PC, and PSL. The Screen 
Management Facility stores the argument you supply in this structure. 


data structure 


address of data structure 


SMG$I_PASTEBOARD_ID 

RO 

SMG$I_ARG 

Rl 

filled with spaces 

i 

1 

PC 


31 8 7 

0 

PSL 

SMG$B_CHARACTER _ 


ZK-4804-85 


The first longword contains the pasteboard-id and has the symbolic name 
SMG$L_PASTEBOARD_ID. The second longword contains the AST- 
argument and has the symbolic name SMG$L_ARG. The third longword 
contains the ASCII value of the out-of-band character typed and can be 
accessed by way of two symbolic names: SMG$B_CHARACTER (the low- 
order byte containing the ASCII value) and SMG$L—CHARACTER (the 
longword containing the ASCII value in the low-order byte and spaces in the 
high-order bytes). 


DESCRIPTION SMG$SET—OUT—OF—BAND—ASTS enables or disables the acceptance of 

out-of-band characters at the specified terminal. If one of these characters is 
typed at the terminal, the AST routine is called. 


CONDITION 

VALUES 

RETURNED 


SSS—NORMAL 

SMG$_WRONUMARG 

SMG$_INVPAS_ID 


Normal successful completion. 
Wrong number of arguments. 
Invalid pasteboard-id. 
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SMG$SET_PHYSICAI_CURSOR 


SMG$SET_PHYSICAI_CURSOR 

Set Cursor on Physical Screen 



SMG$SET_PHYSICAI_CURSOR moves the physical cursor to the 

specified position on the physical screen. 

• 

FORMAT 

SMG$SET_PHYSICAI—CURSOR 

pasteboard-id , pb-row 
,pb-column 


RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

• 

ARGUMENTS 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the physical screen whose physical cursor is to move. The 
pasteboard-id argument is the address of an unsigned longword that contains 
the pasteboard identifier. 

Pasteboard-id is returned by SMG$CREATE_PASTEBOARD. 

• 


pb-row 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the row to which the physical cursor moves. The pb-row argument 
is the address of an unsigned longword that contains the row number. 



pb-column 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the column to which the physical cursor moves. The pb-column 
argument is the address of an unsigned longword that contains the column 
number. 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


SMG$SET_PHYSICAL_CURSOR moves the physical cursor to the specified 
row and column position on a terminal screen. 


SSS—NORMAL 

SMG$_WRONUMARG 

SMG$_INVPAS_ID 

SMG$_INVARG 


Normal successful completion. 
Wrong number of arguments. 
Invalid pasteboard-id. 

Invalid column. 
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SMG$SNAPSHOT—Write Snapshot 



SMG$SNAPSHOT writes the current pasteboard buffer to the file or 
hardcopy terminal specified by pasteboard-id. 

FORMAT 

SMG$SNAPSHOT pasteboard-id[,ff-flag] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the file or hardcopy terminal to receive the contents of the 
pasteboard buffer. The pasteboard-id argument is the address of an 
unsigned longword that contains the pasteboard identifier. The output device 
assiocated with pasteboard-id is specified by the output-device argument of 
SMG$CREATE-PASTEBOARD. 

ff-flag 

VMS Usage: boolean 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Form-feed flag. The ff-flag argument is the address of an unsigned longword 
containing a Boolean value. If the value of ff-flag is 1, then the first record 
output will be a form feed ( <FF> ). If the value of ff-flag is zero, then an 
initial form-feed record will not be output. 

DESCRIPTION 

SMG$SNAPSHOT is meant to be used primarily when output to the terminal 
is controlled by RMS — that is, when the output device is a file, a hardcopy 
terminal, or a terminal of unknown type. In this case, the pasteboard 
information is stored internally and is sent to either the file, hardcopy 
terminal, or the terminal of unknown type whenever SMG$SNAPSHOT 
is called. This allows you to capture screenlike images in a file. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SMG$_NOTRMSOUT Successful completion. No action was taken 

because output is not controlled by RMS. 

Any condition value returned by RMS. 
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SMG$UNPASTE_VIRTUAL-DISPLAY 
Remove Virtual Display 



SMG$UNPASTE_VIRTUAL-DISPLAY removes a virtual display 
from a pasteboard. 

FORMAT 

SMG$UNPASTE_VIRTUAI_DISPLAY 

display-id,pasteboard-id 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

display-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the virtual display to be removed from a pasteboard. The display-id 
argument is the address of an unsigned longword that contains the display 
identifier. 

Display-id is returned by SMGSCREATE -VIRTUAL -DISPLAY. 

pasteboard-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Specifies the pasteboard (physical screen) from which the virtual display 
is removed. The pasteboard-id argument is the address of an unsigned 
longword that contains the pasteboard identifier. 

DESCRIPTION 

SMG$UNPASTE—VIRTUAL -.DISPLAY removes the specified display from 
the specified pasteboard, and thus from the screen associated with the 
pasteboard. This routine does not destroy the virtual display or its contents; 
it merely removes its association with a particular pasteboard and hence its 
visibility on the screen. Any text that was occluded by the specified virtual 
display becomes visible again. 
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VALUES 

RETURNED 


Run-Time Library Routines 

SMG$UN PASTE_VIRTU Al_DISPLAY 


SS$_NORMAL 

SMG$_INVPAS_ID 

SMG$_INVDIS_ID 

SMG$_WRONUMARG 

SMG$_INVARG 

SMG$_NOTPASTED 


Normal successful completion. 

Invalid pasteboard-id. 

Invalid display-id. 

Wrong number of arguments. 

Invalid argument. The specified virtual display is 
not pasted to the specified pasteboard. 

The specified virtual display is not pasted to the 
specified pasteboard. 
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STR$ADD—Add Two Decimal Strings 



STR$ADD adds two strings of digits. 

FORMAT 

STR$ADD asign ,aexp ,adigits , bsign ,bexp ,bdigits 
,csign ,cexp ,cdigits 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

asign 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Sign of the first operand. The asign argument is the address of an unsigned 
longword containing this sign. Zero is considered positive; 1 is considered 
negative. 

aexp 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Power of 10 by which adigits has to be multiplied to get the absolute value 
of the first operand. The aexp argument is the address of a signed longword 
integer containing this exponent. 

adigits 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String of unsigned digits representing the absolute value of the first operand 
before aexp is applied. The adigits argument is the address of a descriptor 
pointing to this string. This string must be an unsigned decimal number. 

bsign 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Sign of the second operand. The bsign argument is the address of an 
unsigned longword containing the second operand's sign. Zero is considered 
positive; one is considered negative. 
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bexp 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Power of 10 by which bdigits has to be multiplied to get the absolute 
value of the second operand. The bexp argument is the address of a signed 
longword integer containing the second operand's exponent. 

bdigits 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String of unsigned digits representing the absolute value of the second 
operand before bexp is applied. The bdigits argument is the address of a 
descriptor pointing to this string. This string must be an unsigned decimal 
number. 


csign 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Sign of the result. The csign argument is the address of a signed longword 
integer containing the result's sign. Zero is considered positive. 


cexp 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Power of 10 by which cdigits has to be multiplied to get the absolute value 
of the result. The cexp argument is the address of a signed longword integer 
containing the result's exponent. 


cdigits 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
write only 
by descriptor 


String of unsigned digits representing the absolute value of the result before 
cexp is applied. The cdigits argument is the address of a descriptor pointing 
to this string. This string is an unsigned decimal number. 


DESCRIPTION STR$ADD adds two strings of decimal numbers (a and b). Each number to 
be added is passed to STR$ADD in three arguments: 

1 xdigits—the string portion of x 

2 xexp—the power of ten needed to obtain the absolute value of x 

3 xsign—the sign of x 
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The value of the number x is derived by multiplying xdigits by lOxexp and 
applying xsign. Therefore, if xdigits is equal to '2' and xexp is equal to 3 and 
xsign is equal to 1, then the number represented in the x arguments is 2 * 

10 3 plus the sign, or -2000. 

The result of the addition (c) is also returned in those three parts. 


CONDITION 

VALUES 

RETURNED 

SS$_NORMAL 

STR$_TRU 

Routine successfully completed. 

String truncation warning. The fixed-length 
destination string could not contain all the 
characters. 

CONDITION 

LIB$_INVARG 

Invalid argument. 

VALUES 

STR$_FATINTERR 

Fatal internal error. An internal consistency check 

SIGNALED 


has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 


STR$_ILLSTRCLA 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 


STR$_INSVIRMEM 

Insufficient virtual memory. STR$ADD could not 
allocate heap storage for a dynamic or temporary 
string. 


STR$_WRONUMARG 

Wrong number of arguments. 


EXAMPLE 


! This is a sample arithmetic program 
! showing the use o t STR$ADD to add 
! two decimal strings. 


asign 7. * iy. 
AEXPy. * 37. 
ADIGITSI = '1' 
BSIGN7. = oy. 
BEXP7. = -4% 
BDIGITSt = '2' 
CSIGN7, = 07. 
CEXPX * 01 
CDIGITSI * 'O' 
PRINT "A = 
PRINT "B = 
CALL STRIADD 


PRINT "C = 
999 END 


ASIGN7.; AEXP7.; ADIGITS$ 

BSIGN7,; BEXP7,; BDIGITS$ 

(ASIGN7,, AEXP7., ADIGITS$, 
BSIGN7., BEXP7., BDIGITS$. 
CSIGN7., CEXP7., CDIGITS$) 
CSIGN7,; CEXP7.; CDIGITSl 


k 

k 


This BASIC example uses STR$ADD to add two decimal strings, where the 
following values apply: 

A = -1000 (ASIGN = 1, AEXP = 3, ADIGITS = T) 

B = .0002 (BSIGN = 0, BEXP = -4, BDIGITS = '2') 
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The output generated by this program is listed below; note that the decimal 
value of C = -999.9998 (CSIGN = 1, CSIGN = -4, CDIGITS = / 9999998 / ). 

A = 1 3 1 

B = 0 -4 2 
C = 1 -4 9999998 
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STR$ANALYZE_SDESC—Analyze String 



Descriptor 

STR$ANALYZE_SDESC extracts the length and starting address of 
the data for a variety of string descriptor classes. 

FORMAT 

STR$ANALYZE_SDESC inp-dsc Jen ,data-adr 

corresponding 
jsb entry point 

STR$ANALYZE_SDESC_R1 

RETURNS 

VMS Usage: cond_value 
type: longword integer (signed) 

access: write only 

mechanism: by value 

ARGUMENTS 

inp-dsc 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Input descriptor from which STR$ANALYZE_SDESC extracts the length of 
the data and the address at which the data starts. The inp-dsc argument is 
the address of a descriptor pointing to the input data. 

len 

VMS Usage: word-signed 
type: word integer (signed) 

access: write only 

mechanism: by reference for CALL entry point, 
by value for JSB entry point 

Length of the data; this length is extracted from the descriptor by 
STR$ANALYZE_SDESC. The len argument is the address of a signed 
word integer into which STR$ANALYZE_SDESC writes the data length. 

data-adr 

VMS Usage: address 

type: longword (unsigned) 

access: write only 

mechanism: by reference for CALL entry point, 
by value for JSB entry point 

Address of the data; this address is extracted from the descriptor by 
STR$ANALYZE_SDESC. The data-adr argument is an unsigned longword 
into which STR$ANALYZE_SDESC writes the address of the data. 
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DESCRIPTION 

STR$ANALYZE_SDESC takes as input a descriptor argument and extracts 
from the descriptor the length of the data and the address at which the data 
starts for a variety of string descriptor classes. See LIB$ANALYZE_SDESC 
for a list of classes. 

STR$ANALYZE_SDESC returns the length of the data in the len argument 
and the starting address of the data in the data-adr argument. 

STR$ANALYZE_SDESC signals an error if an invalid descriptor class is 
found. 

CONDITION 

VALUES 

SIGNALED 

STR$_ILLSTRCLA Illegal string class. The class code found in the 

class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 


RTL-765 






Run-Time Library Routines 

STR$APPEND 


STR$APPEND—Append String 



STR$APPEND appends a source string to the end of a destination 
string. The destination string must be a dynamic or varying string. 

FORMAT 

STR$APPEND dst-str,src-str 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string to which STR$APPEND appends the source string. The 
dst-str argument is the address of a descriptor pointing to the destination 
string. This destination string must be dynamic or varying. 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string that STR$APPEND appends to the end of the destination string. 
The src-str argument is the address of a descriptor pointing to this source 
string. 

CONDITION 

VALUE 

RETURNED 

SS$_NORMAL Routine successfully completed. 
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CONDITION STR$_FATINTERR 

VALUES 

SIGNALED 

STR$_ILLSTRCLA 


STR$_JNSVIRMEM 


STR$_STRT OOLON 


Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 

Insufficient virtual memory. STR$APPEND could 
not allocate heap storage for a dynamic or 
temporary string. 

The combined lengths of the source and destination 
strings exceeded 65,535. 


EXAMPLE 


This example program uses 
STR$APPEND to append a source 
string to a destination string. 


DSTI = 'VAX/' 

SRC$ = 'VMS' 

CALL STR$APPEND (DST$, SRC$) 
PRINT "DST$ = ";DST$ 

END 


This BASIC example uses STR$APPEND to append a source string 'VMS 7 , to 
a destination string 7 VAX/ 7 . 

The output generated by this program is as follows: 

DST$ = VAX/VMS 
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STR$CASE_BLIND_COMPARE 
Compare Strings Without Regard to Case 

STR$CASE_BLIND_COMPARE compares two input strings of 
any supported class and data type without regard to whether the 
alphabetic characters are uppercase or lowercase. 


FORMAT STR$CASE_BLIND_COMPARE srcl-str ,src2-str 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 

longword integer (signed) 
write only 
by value 


The values returned by STR$CASE_BLIND_COMPARE and the conditions 
to which they translate are as follows: 


Returned Value Condition 

-1 Srcl -str is less than src2-str 

0 Both are the same (with blank fill for shorter string) 

1 Srcl -str is greater than src2-str 


ARGUMENTS 


srcl-str 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


First string. The srcl-str argument is the address of a descriptor pointing to 
the first string. 


src2-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Second string. The src2-str argument is the address of a descriptor pointing 
to the second string. 


DESCRIPTION STR$CASE_BLIND_COMPARE does not distinguish between uppercase and 

lowercase characters. The contents of both strings are converted to uppercase 
before the strings are compared, but the source strings themselves are not 
changed. STR$CASE_BLIND__COMPARE uses the DEC Multinational 
Character Set. 
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CONDITION STR$_ILLSTRCLA 

VALUE 

SIGNALED 


Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 


EXAMPLE 


PROGRAM CASE_BLIND(INPUT. OUTPUT); 

{+} 

< This program demonstrates the use of 
{ STR$CASE_BLIND_COMPARE. 

{ 

{ First, declare the external function. 

{-> 

FUNCTION STR$CASE_BLIND_COMPARE(STR1 : VARYING 
[A] OF CHAR; STR2 : VARYING [B] OF 
CHAR) : INTEGER; EXTERN; 


<+> 

I Declare the variables to be used in the 
{ main program. 

{-> 

VAR 

STRING1 : VARYING [256] OF CHAR; 

STRING2 : VARYING [256] OF CHAR; 

RET.STATUS : INTEGER; 

{+> 

{ Begin the main program. Read values for 
{ the strings to be compared. Call 
{ STR$CASE_BLIND_COMPARE. Print the 
{ result. 

{-> 

BEGIN 

WRITELNCENTER THE FIRST STRING: '); 

READLN(STRINGi); 

WRITELNCENTER THE SECOND STRING: '); 

READLNCSTRING2); 

RET.STATUS := STR$CASE_BLIND_C0MPARE(STRING1, STRING2); 
WRITELN(RET_STATUS); 

END. 


This PASCAL example shows how to call STR$CASE_BLIND_COMPARE to 
determine whether two strings are equal regardless of case. One example of 
the output of this program is as follows: 

$ RUN CASE.BLIND 
ENTER THE FIRST STRING: KITTEN 
ENTER THE SECOND STRING: kltTeN 
0 
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STR$COMPARE—Compare Two Strings 

STR$COMPARE compares the contents of two strings. If the 



strings are unequal in length, the shorter string is considered to 
be filled with blanks to the length of the longer string before the 
comparison is made. 

FORMAT 

STR$COMPARE srcl-str,src2-str 

RETURNS 

VMS Usage: cond_value 
type: longword integer (signed) 

access: write only 

mechanism: by value 

The values returned by STR$COMPARE and the conditions to which they 
translate are as follows: 

Returned Value Condition 

-1 Srcl -str is less than src2-str 

0 Srcl -str is equal to src2-str 

1 Srcl -str is greater than src2-str 

ARGUMENTS 

srcl-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

First string. The srcl-str argument is the address of a descriptor pointing to 
the first string. 

src2-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Second string. The src2-str argument is the address of a descriptor pointing 
to the second string. 

CONDITION 

VALUE 

SIGNALED 

STR$_ILLSTRCLA Illegal string class. The class code found in the 

class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 
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EXAMPLE 


100 EXTERNAL INTEGER FUNCTION STR$COMPARE 
SRC1$ = 'ABC' 

SRC2$ = 'BCD 


Note that STRlCOMPARE will treat SRC1$ as if it were the same 
length as SRC2$ for the purpose of the comparison. Thus, it 
will treat the contents of SRC1$ as 'ABC '. However, it 

will only 'treat' the contents as longer; the contents of 
the source string are not actually changed. 


1% = STRlCOMPARE(SRC1$, SRC2$) 

IF I % = 1 THEN RESULT! = ' IS GREATER THAN 
IF 1 % = 0 THEN RESULT! = ' IS EQUAL TO ' 

IF 1% = -1 THEN RESULT! = ' IS LESS THAN ' 
PRINT SRC1I; RESULT!; SRC2I 
999 END 


This BASIC program uses STR$COMPARE to compare two strings. The 
output generated by this program is as follows: 

ABC IS LESS THAN BCD 
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STR$COMPARE_EQL—Compare Two 

Strings for Equality 

STR$COMPARE_EQL compares two strings to see if they have the 
same length and contents. Uppercase and lowercase characters are 
not considered equal. 


FORMAT STR$COMPARE__EQL srcl-str,src2-str 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


The values returned by STR$COMPARE and the conditions to which they 
translate are as follows: 


Returned Value 

Condition 

0 

The length and the contents of srcl -str are equal to the 
length and contents of src2-str. 

1 

Either the length of srcl -str is not equal to the length of 
src2-str, or the contents of srcl -str are not equal to the 
contents of src2-str, or both. 


ARGUMENTS 


srcl-str 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 

First source string. The srcl-str argument is the address of a descriptor 
pointing to the first source string. 


src2-str 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Second source string. The src2-str argument is the address of a descriptor 
pointing to the second source string. 


CONDITION STR$_ILLSTRCLA 

VALUE 

SIGNALED 


Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 
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EXAMPLE 


PROGRAM COMPARE_EQL(INPUT, OUTPUT); 

<♦> 

< This program demonstrates the use of 

{ STR$COMPARE_EQL to compare two strings. 

{ Strings are considered equal only if they 
{ have the same contents and the same length. 

< 

{ First, declare the external function. 

{-> 

FUNCTION STR$COMPARE_EQL(SRC1STR : VARYING 
[A] OF CHAR; SRC2STR : VARYING [B] 

OF CHAR) : INTEGER; EXTERN; 

{+> 

{ Declare the variables used in the main program. 
{-> 

VAR 

STRING1 : VARYING [256] OF CHAR; 

STRING2 : VARYING [256] OF CHAR; 

RET.STATUS : INTEGER; 

<♦} 

< Begin the main program. Read the strings 
{ to be compared. Call STR$COMARE_EQL to compare 
{ the strings. Print the result. 

<-> 

BEGIN 

WRITELN('ENTER THE FIRST STRING: '); 
READLN(STRINGl); 

WRITELN CENTER THE SECOND STRING: *); 

READLN(STRING2); 

RET.STATUS := STR$COMPARE_EQL(STRINGi, STRING2); 
WRITELN(RET.STATUS); 

END. 


This PASCAL example demonstrates the use of STR$COMPARE_EQL. A 
sample of the output generated by this program is as follows: 

$ RUN COMPARE.EQL 
ENTER THE FIRST STRING: frog 
ENTER THE SECOND STRING: Frogs 
1 
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STR$COM PARE_M U LTI—Compare Two 
Strings for Equality Using Multinational 
Character Set 

STR$COMPARE_MULTI compares two character strings for equality 
using the DEC Multinational character set. 


FORMAT 


STR$COMPARE_MULTI srcl-str,src2-str 

[, case-blind-flag] 
[,foreign-lang] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 

longword integer (signed) 
write only 
by value 


The values returned by STR$COMPARE_MULTI and the conditions to which 
they translate are as follows: 


Returned Value Condition 

-1 Srcl -str is less than src2-str. 

0 Both strings are the same; the shorter string is blank filled. 

1 Srcl -str is greater than src2-str. 


ARGUMENTS 


srcl-str 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 

First string in the comparison. The srcl-str argument is the address of a 
descriptor pointing to the first string. 


src2-str 

VMS Usage 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 

Second string in the comparison. The src2-str argument is the address of a 
descriptor pointing to the second string. 
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case-blind-flag 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by value 


A single flag bit. The case-blind-flag argument is a signed longword integer 
that contains this flag bit. The default value of case-blind-flag is zero. 


Bit 

Symbol 

Meaning 

0 

CASEBLIND 

If set, uppercase and lowercase characters are equivalent. 


foreign-lang 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by value 

Indicator which determines the foreign language table to be used. The 
foreign-lang argument is an unsigned longword that contains this foreign 
language table indicator. The default value of foreign-lang is 1. 


Value 

Language 

1 

Multinational table 

2 

Danish table 

3 

Finnish/Swedish table 

4 

German table 

5 

Norwegian table 

6 

Spanish table 


DESCRIPTION STR$COMPARE_MULTI compares two character strings to see if they have 

the same contents. Two strings are "equal" if they contain the same characters 
in the same sequence, even if one of them is blank filled to a longer length 
than the other. The DEC Multinational character set, or foreign language 
variations of the DEC Multinational character set, is used in the comparison. 

See the VAX/VMS I/O Reference Volume for more information about the DEC 
Multinational character set. 


CONDITION STR$_ILLSTRCLA 

VALUES 

SIGNALED 

LIB$_INVARG 


Illegal string class. Severe error. The descriptor of 
srcl-str and/or src2-str contains an class code 
that is not supported by the VAX Procedure Calling 
and Condition Handling Standard. 

Invalid Argument. Severe error. 
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STR$CONCAT—Concatenate Two or More 

Strings 


STR$CONCAT takes up to 254 source strings and concatenates 
them into a single destination string. 

FORMAT 

STR$CONCAT dst-str,srcl-str[... ,srcn-str] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which STR$CONCAT concatenates all specified source 
strings. The dst-str argument is the address of a descriptor pointing to this 
destination string. 


srcl-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

First source string. The srcl-str argument is the address of a descriptor 
pointing to the first source string. STR$CONCAT requires at least one source 
string. 


srcn-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Nth source string. The scrn-str argument is the address of a descriptor 
pointing to the Nth source string. The largest value of N that STR$CONCAT 
allows is 254. 

DESCRIPTION 

STR$CONCAT concatenates all specified source strings into a single 
destination string. The strings can be of any class and data type, provided 
that the length fields of the descriptors indicate the strings' lengths in bytes. 

A warning status is returned if one or more input characters were not copied 
to the destination string. 
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You must specify at least one source string, and you may specify up to 254 
source strings. The maximum length of the concatenated string is 65,535 
bytes. 


CONDITION 

VALUES 

RETURNED 

SS$_NORMAL 

STR$_TRU 

Routine successfully completed. All characters in 
the input strings were copied into the destination 
string. 

String truncation warning. One or more input 
characters were not copied into the destination 
string. This can happen when the destination is a 
fixed-length string. 

CONDITION 

STR$_FATINTERR 

Fatal internal error. An internal consistency check 

VALUES 


has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 

SIGNALED 


DIGITAL in a Software Performance Report (SPR). 


STR$_ILLSTRCLA 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 


STR$_INSVIRMEM 

Insufficient virtual memory. STR$CONCAT 
could not allocate heap storage for a dynamic or 
temporary string. 


STR$_STRT OOLON 

String length exceeds 65,535 bytes. 


STR$_WRONUMARG 

Wrong number of arguments. You tried to pass 
fewer than 2 or more than 255 arguments to 
STRSCONCAT. 


EXAMPLES 


This example program uses STRlCONCAT 
to concatenate four source strings into a 
single destination string. 


EXTERNAL INTEGER FUNCTION STRlCONCAT 
STATUS'/. = STRlCONCAT (X|, 'A'. 'B'. 'C' . 'D') 
PRINT "XI = ";X| 

END 


The output generated by this BASIC program is as follows: 
X$ = ABCD 
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S 


MSG1: 

MSGl.LEN = .-MSG1 
MSG2: 

MSG2.LEN = .-MSG2 
RESULT: 


.ASCII /David Foster / 
.ASCII /wrote this book./ 
.BLKB MSGl.LEN + MSG2.LEN 


first string 
its length 
second string 
its length 

string to hold concatenation 


MSGl.DSC: .WORD MSGl.LEN 

.BYTE 14 
.BYTE 1 
.ADDRESS MSG1 


DSC$W.LENGTH 

DSC$B_DTYPE 

DSC$B_CLASS 

DSC$A_POINTER 


MSG2.DSC: 


RESULT.DSC: 


.WORD MSG2.LEN 
.BYTE 14 
.BYTE 1 
.ADDRESS MSG2 


DSC$W_LENGTH 
DSC$B_DTYPE 
DSC$B.CLASS 
DSC$A_P0INTER 


.WORD MSGl.LEN + MSG2.LEN 
.BYTE 14 
.BYTE 1 

.ADDRESS RESULT 


DSC$W_LENGTH 

DSCIB.DTYPE 

DSC$B_CLASS 

DSC$A_POINTER 


.ENTRY 

EXAM1, ~M<> ; 

entry point 

PUSHAQ 

MSG2.DSC ; 

Push the descriptors 

PUSHAQ 

MSGl.DSC ; 

in 

reverse order 

PUSHAQ 

RESULT.DSC ; 

. 


CALLS 

#3. G~STR$CONCAT 


; concatenate strings 

PUSHAQ 

RESULT.DSC 


; descr. of string to display 

CALLS 

#1, G^LIBlPUT.OUTPUT 

; display it 

RET 



; return to calling routine 

.END 

EXAM1 




The output generated by this MACRO program is as follows: 
David Foster wrote this book. 
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STR$COPY_DX—Copy a Source String 



Passed by Descriptor to 
a Destination String 

STR$COPY_DX copies a source string to a destination string. Both 
strings are passed by descriptor. 

FORMAT 

STR$COPY_DX dst-str ,src-str 

corresponding 
jsb entry point 

STR$COPY_DX_R8 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which STR$COPY_DX writes the source string. The 
dst-str argument is the address of a descriptor pointing to the destination 
string. 

The class field determines how the copy operation is handled. For further 
information, see the Description section. 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string that STR$COPY_DX copies into the destination string. The 
src-str argument is the address of a descriptor pointing to this source string. 
The descriptor class of the source string can be unspecified, fixed length, 
dynamic, scalar decimal, array, noncontiguous array, or varying. 

(See the description of LIB$ANALYZE_SDESC for possible restrictions.) 

DESCRIPTION 

STR$COPY_DX copies a source string to a destination string, where both 
strings are passed by descriptor. All conditions except truncation are signaled; 
truncation is returned as a warning condition value (bit 0 is clear) in RO. 
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CONDITION 

VALUES 

RETURNED 


CONDITION 

VALUES 

SIGNALED 


STR$COPY_DX passes the source string by descriptor. In addition, an 
equivalent JSB entry point is provided, with RO being the first argument (the 
descriptor of the destination string), and R1 the second (the descriptor of the 
source string). 

Depending on the class of the destination string, the following actions occur: 


Class Field 

Action 

DSC$K_CLASS_S,Z,SD,A,NCA 

Copy the source string. If needed, space is 
filled or truncated on the right. 

DSC$K_CLASS_D 

If the area specified by the destination 
descriptor is large enough to contain the 
source string, copy the source string and set 
the new length in the destination descriptor. 

If the area specified is not large enough, 
return the previous space allocation (if any) 
and then dynamically allocate the amount 
of space needed. Copy the source string 
and set the new length and address in the 
destination descriptor. 

DSC$K_CLASS_VS 

Copy source string to destination string up 
to the limit of DSC$W_MAXSTRLEN with 
no padding. Readjust current length field to 
actual number of bytes copied. 


SS$_NORMAL Procedure successfully completed. All characters 

in the input string were copied to the destination 
string. 

STR$_TRU String truncation warning. The fixed-length 

destination string could not contain all of the 
characters copied from the source string. 


STR$_FATINTERR 


STR$_ILLSTRCLA 


STR$_INSVIRMEM 


Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 

Insufficient virtual memory. STR$COPY_DX 
could not allocate heap storage for a dynamic or 
temporary string. 
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STR$COPY_R—Copy Source String 



Passed by Reference to 
Destination String 

STR$COPY_R copies a source string passed by reference to a 
destination string. 

FORMAT 

STR$COPY_R dst-str, src-len ,src-str 

corresponding 
jsb entry point 

STR$COPY_R_R8 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which STR$COPY_R copies the source string. The 
dst-str argument is the address of a descriptor pointing to the destination 
string. 

The class field determines the appropriate action. 

src-len 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: read only 

mechanism: by reference 

Length of the source string. The src-len argument is the address of an 
unsigned word containing the length of the source string. 

srcstr 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by reference 

Source string which STR$COPY_R copies into the destination string. The 
src-str argument is the address of the source string. 

See the description of LIB$ANALYZE_SDESC for possible restrictions. 
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DESCRIPTION STR$COPY_R copies a source string passed by reference to a destination 

string. All conditions except truncation are signaled; truncation is returned as 
a warning condition value (bit 0 clear) in RO. 

A JSB entry point is provided, with RO being the first argument, R1 the 
second, and R2 the third. The length argument is passed in bits 15:0 of Rl. 

Depending on the class of the destination string, the following actions occur: 


Class Field 

Action 

DSC$K_CLASS_S,Z,SD,A,NCA 

Copy the source string. If needed, space is 
filled or truncated on the right. 

DSC$K_CLASS_D 

If the area specified by the destination 
descriptor is large enough to contain the 
source string, copy the source string and set 
the new length in the destination descriptor. 

If the area specified is not large enough, 
return the previous space allocation (if any) 
and then dynamically allocate the amount 
of space needed. Copy the source string 
and set the new length and address in the 
destination descriptor. 

DSC$K_CLASS_VS 

Copy source string to destination string up 
to the limit of DSC$W_MAXSTRLEN with 
no padding. Readjust current length field to 
actual number of bytes copied. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

STR$_TRU 


Procedure successfully completed. All characters 
in the input string were copied to the destination 
string. 

String truncation warning. The fixed-length 
destination string could not contain all of the 
characters copied from the source string. 


CONDITION STR$_FATINTERR 

VALUES 

SIGNALED 

STR$_ILLSTRCLA 


STR$_INSVIRMEM 


Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 

Insufficient virtual memory. STR$COPY_R could 
not allocate heap storage for a dynamic or 
temporary string. 
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STR$DIVIDE—Divide Two Decimal Strings 

STR$DIVIDE divides two decimal strings. 

FORMAT 

STR$DIVIDE asign ,aexp ,adigits ,bsign ,bexp 

,bdigits Jot-digits ,rnd-trunc ,csign 
,cexp ,cdigits 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 


asign 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Sign of the first operand. The asign argument is the address of an unsigned 
longword containing the first operand's sign. Zero is considered positive; 1 is 
considered negative. 


aexp 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Power of 10 by which adigits has to be multiplied to get the absolute value 
of the first operand. The aexp argument is the address of the first operand's 
exponent. 

adigits 

VMS Usage: char_string 
type: num. string, unsigned 

access: read only 

mechanism: by descriptor 

First operand's numeric string. The adigits argument is the address of a 
descriptor pointing to the first operand's numeric string. The string must be 
an unsigned decimal number. 


bsign 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Sign of the second operand. The bsign argument is the address of an 
unsigned longword containing the second operand's string. Zero is considered 
positive; 1 is considered negative. 
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bexp 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Power of 10 by which bdigits has to be multiplied to get the absolute value 
of the second operand. The bexp argument is the address of the second 
operand's exponent. 

bdigits 

VMS Usage: char_string 
type: num. string, unsigned 

access: read only 

mechanism: by descriptor 

Second operand's numeric string. The bdigits argument is the address of a 
descriptor pointing to the second operand's number string. The string must 
be an unsigned decimal number. 

tot-digits 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Number of digits to the right of the decimal point. The tot-digits argument 
is the address of s signed longword integer containing the number of total 
digits. STR$DIVIDE uses this number to carry out the division. 

rnd-trunc 

VMS Usage: longword—unsigned 
type: aligned bit string 

access: read only 

mechanism: by reference 

Indicator of whether STR$DIVIDE is to round or truncate the result; zero 
means truncate; 1 means round. The rnd-trunc argument is the address of an 
aligned bit string containing this indicator. 


cstgn 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Sign of the result. The csign argument is the address of a signed longword 
integer containing the sign of the result. Zero is considered positive; 1 is 
considered negative. 


cexp 

VMS Usage: 
type: 
access: 
mechanism: 


longword—signed 
longword integer (signed) 
write only 
by reference 


Power of 10 by which cdigits has to be multiplied to get the absolute value 
of the result. The cexp argument is the address of a signed longword integer 
containing the exponent. 
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cdigits 


VMS Usage: char_string 
type: num. string, unsigned 

access: write only 

mechanism: by descriptor 

Result's numeric string. The cdigits argument is the address of a descriptor 
pointing to the numeric string of the result. This string is an unsigned 
decimal number. 


DESCRIPTION 

STR$DIVIDE divides two decimal strings. The divisor and dividend are 
passed to STR$DIVIDE in three parts: (1) the numeric string, (2) the power 
of 10 needed to obtain the absolute value, and (3) the sign of the decimal 
number. The result of the division is also returned in those three parts. 

CONDITION 

VALUES 

RETURNED 

SS$_N0RMAL 

STR$_TRU 

Routine successfully completed. 

String truncation warning. The fixed-length 
destination string could not contain all of the 
characters. 

CONDITION 

LIB$_INVARG 

Invalid argument. 

VALUES 

STR$_DIVBY_ZER 

Division by zero. 

SIGNALED 

STR$_FATINTERR 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 


STR$_ILLSTRCLA 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 


STR$_INSVIRMEM 

Insufficient virtual memory. STR$DIVIDE could not 
allocate heap storage for a dynamic or temporary 
string. 


STR$_WRONUMARG 

Wrong number of arguments. 


EXAMPLE 


100 


This example program uses STR$DIVIDE 
to divide two decimal strings, and truncate 
the result. 


ASIGN7. = 17. 

AEXP7. = 37. 

ADIGITS! = 1 1 1 
BSIGN7. = 07. 

BEXP7. = -47. 

BDIGITSI = *2' 

CSIGN7. = 07. 

CEXP7. = 07. 

CDIGITS! = 'O' 

PRINT "A = ASIGN7.; AEXP7.; ADIGITS! 
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PRINT "B = BSIGN*/,; BEXP'/.; BDIGITS$ 

CALL STRIDIVIDE (ASIGN%, AEXP'/., ADIGITS$, & 
BSIGN*/., BEXP*/., BDIGITSI, & 

3*/., Oy., CSIGNy., CEXP'/., CDIGITSI) 
PRINT "C = "; CSIGNY.; CEXP*/.; CDIGITSl 
1500 END 


This BASIC program uses STR$DIVIDE to divide two decimal strings, A 
divided by B, where the following values apply: 

A = -1000 (ASIGN = 1, AEXP = 3, ADIGITS = T) 

B = .0002 (BSIGN = 0, BEXP = -4, BDIGITS - '2') 


The output generated by this program is as follows: 


a = 1 
b = o 
c = 1 


3 1 
-4 2 

-3 5000000000 


Thus, the decimal value of C - -5000000 (CSIGN = 1, CEXP = -3, CDIGITS = 
5000000000). 
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STR$DUPI_CHAR—Duplicate Character n 



Times 

STR$DUPI_CHAR generates a string containing n duplicates of 

the input character. If the destination string is an "empty" dynamic 

string descriptor, STR$DUPI_CHAR will allocate and initialize the 

string. 

FORMAT 

ST R$ D U P 1 _C H A R dst-s tr [, length] [, char] 

corresponding 
jsb entry point 

STR$DUPI_CHAR_R8 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which STR$DUPL_CHAR writes length copies of the 
input character. The dst-str argument is the address of a descriptor pointing 
to the destination string. 

length 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Number of times char will be duplicated. The length argument is the address 
of a signed longword integer containing the number. This is an optional 
argument. If omitted, the default is 1. 

char 

VMS Usage: byte_unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by reference 

ASCII character which STR$DUPL_CHAR writes length times into the 
destination string. The char argument is the address of an unsigned byte 
containing this character. This is an optional argument. If omitted, the 
default is a space. 
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CONDITION 

SS$_NORMAL 

Routine successfully completed. 

VALUES 

RETURNED 

STR$_NEGSTRLEN 

Routine successfully completed. The length 
argument contained a negative value; zero was 
used. 


STR$_TRU 

String truncation warning. The fixed-length 
destination string could not contain all of the 
characters. 

CONDITION 

VALUES 

SIGNALED 

STR$_FATINTERR 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 


STR$_ILLSTRCLA 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 


STR$_INSVIRMEM 

Insufficient virtual memory. STRSDUPI_CHAR 

could not allocate heap storage for a dynamic or 
temporary string. 


STR$_STRT OOLON 

String length exceeds 65,535 bytes. 


EXAMPLE 


This example uses STR$DUPL_CHAR to 
duplicate the character 'A' lour times. 


EXTERNAL INTEGER FUNCTION STR$DUPL_CHAR 
STATUS7, = STR$DUPL_CHAR (X$, 4%. 'A' BY REF) 
PRINT X$ 

END 


These BASIC statements set X$ equal to 'AAAA'. 
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STR$FIND_FIRST—IN_SET—Find First 
Character in a Set of Characters 



STR$FIND_FIRST_IN_SET searches a string one character at a time, 
from left to right, comparing each character in the string to every 
character in a specified set of characters for which it is searching. 
STR$FIND_FIRST_IN_SET returns the position in the string where 
the first matching character was found. Zero is returned if no match 
is found. 

FORMAT 

STR$FIND_FIRST_IN_SET src-str ,set-of-chars 

RETURNS 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: write only 

mechanism: by value 

Position in src-str where the first match is found; zero if no match is found. 

ARGUMENTS 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String which STR$FIND_FIRST_IN_SET compares to the set of characters, 
looking for the first match. The src-str argument is the address of a descriptor 
pointing to the character string. 

set-of-chars 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Set of characters which STR$FIND__FIRST_IN_SET is searching for in the 
string. The src-str argument is the address of a descriptor pointing to the set 
of characters. 

DESCRIPTION 

STR$FIND_FIRST_IN_SET compares each character in the string to every 
character in the specified set of characters. As soon as the first match is 
found, STR$FIND_FIRST_IN_SET returns the position in the string where 
the matching character was found. If no match is found, 0 is returned. If 
either src-str or set-of-chars is of zero length, 0 is returned. 
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CONDITION STR$_ILLSTRCLA 

VALUE 

SIGNALED 


Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 


EXAMPLE 


PROGRAM FIND_FIRST(INPUT. OUTPUT); 

{+> 

{ This example uses STR$FIND_FIRST_IN_SET 
{ to find the first character in the source 
{ string (STRING1) which matches a character 
{ in the set of characters being searched for 
{ (CHARS). 

{ 

{ First, declare the external function. 

{-> 

FUNCTION STR$FIND_FIRST_IN_SET(STRING : 

VARYING [A] OF CHAR; SETOFCHARS : 

VARYING [B] OF CHAR) : INTEGER; 

EXTERN; 

{+> 

{ Declare the variables used in the main program. 

{-> 

VAR 

STRING1 : VARYING [256] OF CHAR; 

CHARS : VARYING [256] OF CHAR; 

RET.STATUS : INTEGER; 

{+> 

{ Begin the main program. Read the source string 
{ and the set of characters being searched for. Call 
{ STR$FIND_FIRST_IN_SET to find the first match. 

{ Print the result. 

{-> 

BEGIN 

WRITELN('ENTER THE STRING: '); 

READLN(STRING1); 

WRITELN('ENTER THE SET OF CHARACTERS: '); 

READLN(CHARS); 

RET.STATUS := STR$FIND_FIRST_IN_SET(STRING1, CHARS); 
WRITELN(RET.STATUS); 

END. 


This PASCAL program demonstrates the use of STR$FIND_FIRST_IN_SET. 
If you run this program and set STRING 1 equal to ABCDEFGHIJK and 
CHARS equal to XYZA, the value of RET—STATUS will be 1. 
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STR$FIND_FIRST_NOT_IN_SET 

Find First Character that Does Not Occur 

in Set 


STR$FIND_FIRST_NOT_IN_SET searches a string, comparing 
each character to the characters in a specified set of characters. 
The string is searched character by character, from left to right. 
STR$FIND_FIRST_NOT_IN_SET returns the position of the first 
character in the string that does not match any of the characters in 
the selected set of characters. 


FORMAT STR$FIND_FIRST_NOT_IN_SET src-str 

,set-of-chars 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


longword—signed 
longword integer (signed) 
write only 
by value 


Position in src-str where a nonmatch was found. 


Returned value 

Condition 

0 

Either all characters in src-str match some character in 
set-of-chars, or there were no characters in set-of-chars. 

1 

Either the first nonmatching character in src-str was found 
in position 1, or there were no characters in src-str. 

N 

The first nonmatching character was found in position N 
within src-str. 


ARGUMENTS 


src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String which STR$FIND__FIRST_NOT_IN_SET searches. The src-str 
argument is the address of a descriptor pointing to the string. 


set-of-chars 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

The set of characters which STR$FIND_FIRST_NOT_IN_SET compares to 
the string, looking for a nonmatch. The set-of-chars argument is the address 
of a descriptor pointing to this set of characters. 
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DESCRIPTION STR$FIND_FIRST_NOT_IN_SET searches src-str one character at a time, 

from left to right, comparing each character in the string to every character 
in set-of-chars. When STR$FIND_FIRST_NOT_IN_SET finds a character 
from the string that is not in set-of-chars, it stops searching and returns, as 
the value of STR$FIND_FIRST_NOT_JN—SET, the position in src-str where 
it found the nonmatching character. If all characters in the string match some 
character in the set of characters, STR$FIND_FIRST_NOT_IN_SET returns 
0. If the string is of zero length, the position returned is 1 since none of 
the elements in the set of characters (particularly the first element) will be 
found in the string. If there are no characters in the set of characters, zero is 
returned since "nothing" can always be found. 


CONDITION STR$_ILLSTRCLA 

VALUE 

SIGNALED 


Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 


EXAMPLE 


PROGRAM N0T_IN_SET(INPUT, OUTPUT); 

{♦> 

< This example uses STR$FIND_FIRST_NOT_IN_SET 

{ to find the position of the first nonmatching 
{ character from a set of characters (CHARS) 

{ in a source string (STRING1). 

< 

< First, declare the external function. 

<-> 

FUNCTION STR$FIND_FIRST_NOT_IN_SET(STRING : 

VARYING [A] OF CHAR; SETOFCHARS : 

VARYING [B] OF CHAR) : INTEGER; 

EXTERN; 

{*> 

{ Declare the variables used in the main program. 

{-> 

VAR 

STRING1 : VARYING [256] OF CHAR; 

CHARS : VARYING [256] OF CHAR; 

RET.STATUS : INTEGER; 

{♦> 

{ Begin the main program. Read the source string 
{ and set of characters. Call STR$FIND_FIRST_NOT_IN_SET. 
{ Print the result. 

{-> 

BEGIN 

WRITELN('ENTER THE STRING: '); 

READLN(STRING1); 

WRITELN CENTER THE SET OF CHARACTERS: '); 

READLN(CHARS); 

RET.STATUS := STR$FIND_FIRST_NOT_IN_SET(STRING1, CHARS); 
WRITELN(RET.STATUS); 

END. 


This PASCAL program demonstrates the use of STR$FIND_FIRST_NOT_ 
IN_SET. If you run this program and set STRING 1 equal to FORTUNATE 
and CHARS equal to FORT, the value of RET_STATUS will be 5. 
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STR$FIIMD_FIRST_SUBSTRIIMG—Find First 
Substring in Input String 

STR$FIND_FIRST_SUBSTRING finds the first substring (in a 
provided list of substrings) occurring in a given string. 


FORMAT 


STR$FIND_FIRST_SUBSTRING 

src-str, index ,sub-string-index 
, substring 1... 

[,sub-stringn] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by value 


The values returned by STR$FIND_FIRST_SUBSTRING and the conditions 
to which they translate are as follows: 


Returned Value Condition 

0 Src-str did not contain any of the specified substrings. 

1 STR$FIND_FIRST_SUBSTRING found at least one of the 

specified substrings in the string. 


ARGUMENTS 


src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String that STR$FIND_FIRST_SUBSTRING searches. The src-str argument 
is the address of a descriptor pointing to the string. 

index 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Earliest position within src-str at which STR$FIND_FIRST_SUBSTRING 
found a matching substring; zero if no matching substring was found. The 
index argument is the address of a signed longword integer containing this 
position. 


I 
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sub-string-index 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Ordinal number of the sub-string that matched (1 for the first, 2 for the 
second, and so on), or zero if STR$FIND_FIRST_SUBSTRING found no 
substrings that matched. The sub-string-index argument is the address of a 
signed longword integer containing this ordinal number. 

sub-string 1 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

First specified substring for which STR$FIND_FIRST_SUBSTRING searches 
in src-str. The src-str argument is the address of a descriptor pointing to the 
first substring. 

sub-stringn 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Nth specified substring which STR$FIND_FIRST_SUBSTRING will search 
for in the string. The sub-stringn argument is the address of a descriptor 
pointing to the Nth substring. 

DESCRIPTION 

STR$FIND_FIRST_SUBSTRING takes as input a string to be searched and an 
unspecified number of substrings for which to search. It searches the specified 
string and returns the position of the substring which is found earliest in the 
string. This is not necessarily the position of the first substring specified. (See 
the example at the end of this routine description.) 

Unlike many of the compare and search routines, STR$FIND_FIRST— 
SUBSTRING does not return the position in a return value. The position of 
the substring which is found earliest in the string is returned in the index 
argument. If none of the specified substrings are found in the string, the 
value of index is zero. 

Zero length strings, or 'null' arguments, produce unexpected results. Any time 
the procedure is called with a null substring as an argument, STR$FIND— 
FIRST-SUBSTRING will always return the position of the null substring as 
the first substring found. All other substrings will be interpreted as appearing 
in the string after the null string. 

CONDITION 

VALUES 

SIGNALED 

STR$_ILLSTRCLA Illegal string class. The class code found in the 

class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 

STR$_WRONUMARG Wrong number of arguments. You must supply at 

least one substring. 
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EXAMPLE 


1 ! + 

! This is a BASIC program demonstrating the use of 
! STR$FIND_FIRST_SUBSTRING. This program takes as input 
! four strings which are listed in a data statement 
! at the end of the program. STR$FIND_FIRST_SUBSTRING 
! is called four times (once for each string) 

! to find the first substring occuring in the given 
! string. 

; - 

OPTION TYPE = EXPLICIT 

DECLARE STRING MATCH.STRING 

DECLARE LONG RET.STATUS. k 

INDEX, k 
I, k 

SUB.STRING.NUM 

EXTERNAL LONG FUNCTION STR$FIND_FIRST_SUBSTRING 

FOR I ■ 1 TO 4 

READ MATCH.STRING 

RET.STATUS = STR$FIND_FIRST_SUBSTRING( MATCH.STRING. k 
INDEX, SUB.STRING.NUM, 'ING', 'TH', ’CK') 

IF RET.STATUS = 07. THEN 

PRINT MATCH.STRING;" did not contain any of the substrings" 

ELSE 

SELECT SUB.STRING.NUM 
CASE 1 

PRINT MATCH.STRING;" contains ING at position";INDEX 
CASE 2 

PRINT MATCH.STRING;" contains TH at position";INDEX 
CASE 3 

PRINT MATCH.STRING;" contains CK at position";INDEX 
END SELECT 
END IF 
NEXT I 

2 DATA CHUCKLE, RAINING, FOURTH, THICK 

3 END 


This BASIC program demonstrates the use of STR$FIND_FIRST_ 
SUBSTRING. The output generated by this program is as follows: 

$ BASIC FINDSUB 
$ LINK FINDSUB 
$ RUN FINDSUB 

CHUCKLE contains CK at position 4 
RAINING contains ING at position 5 
FOURTH contains TH at position 5 
THICK contains TH at position 1 

Note that "THICK" contains both the substrings "TH" and "CK". However, 
since "TH" occurs earlier in the string than "CK", its ordinal number is 
returned in substring-index, and the point at which "TH" occurs is returned 
in index. 
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STR$FREE1_DX—Free One Dynamic 



String 

STR$FREE1_DX deallocates one dynamic string. 

FORMAT 

STR$FREE1 _DX dsc-adr 

corresponding 
jsb entry point 

STR$FREE1 _DX_R4 

RETURNS 

VMS Usage: cond__value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

dsc-adr 

VMS Usage: char_string 
type: character string (unsigned) 

access: modify 

mechanism: by descriptor 

Dynamic string descriptor of the dynamic string which STR$FREE1_DX 
deallocates. The dsc-adr argument is the address of a descriptor pointing to 
the string to be deallocated. The class field (DSC$B_CLASS) is checked. 

DESCRIPTION 

STR$FREE1_DX deallocates the described string space and flags the 
descriptor as describing no string at all (DSC$A_POINTER = 0, DSC$W_ 
LENGTH = 0). 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Procedure successfully completed. 

CONDITION 

VALUES 

SIGNALED 

STR$_FATINTERR Fatal internal error. An internal consistency check 

has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

STR$_ILLSTRCLA Illegal string class. The class code found in the 

class field of a descriptor is not a string class 


code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 
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STR$GET1_DX—Allocate One Dynamic 



String 

STR$GET1_DX allocates a specified number of bytes of dynamic 
virtual memory to a specified dynamic string descriptor. 

FORMAT 

STR$GET1_DX ten ,str 

corresponding 
jsb entry point 

STR$GET1_DX_R4 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

len 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: read only 

mechanism: by reference 

Number of bytes which STR$GET1_DX allocates. The len argument is the 
address of an unsigned word containing this number. 

str 

VMS Usage: char_string 
type: character string 

access: modify 

mechanism: by descriptor 

Dynamic string descriptor to which STR$GET1_DX allocates the area. The 
str argument is the address of an unsigned quadword containing the string 
descriptor. 

The class field (DSC$B_CLASS) is checked. 

DESCRIPTION 

STR$GET1_DX allocates a specified number of bytes of dynamic virtual 
memory to a specified string descriptor. The descriptor must be dynamic. 

If the string descriptor already has dynamic memory allocated to it, but the 
amount allocated is less than len, STR$GET1_DX deallocates that space 
before it allocates new space. 

STR$GET1_DX is the only recommended method for allocating a dynamic 
descriptor. Simply filling in the length and pointer fields of a dynamic 
string descriptor can cause serious and unexpected problems with string 
management. 

To deallocate dynamic strings, call STR$FREE1_DX. 
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CONDITION 

VALUE 

RETURNED 


CONDITION 

VALUES 

SIGNALED 


SSS—NORMAL Procedure successfully completed. 


STR$_FATINTERR 


STR$_ILLSTRCLA 


STR$_INSVIRMEM 


Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 

Insufficient virtual memory. STR$GET1_DX 
could not allocate heap storage for a dynamic or 
temporary string. 


RTL-798 






Run-Time Library Routines 

STR$LEFT 


STR$LEFT—Extract a Substring of a String 



STR$LEFT copies a substring of a source string into a destination 
string. 

FORMAT 

STR$LEFT dst-str,src-str,end-pos 

corresponding 
jsb entry point 

STR$LEFT_R8 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which STR$LEFT copies the substring. The dst-str 
argument is the address of a descriptor pointing to the destination string. 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string from which STR$LEFT extracts the substring which it copies 
into the destination string. The src-str argument is the address of a descriptor 
pointing to the source string. 

end-pos 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Relative position in the source string at which the substring ends. The 
end-pos argument is the address of a signed longword integer containing the 
ending position. 

STR$LEFT copies all characters in the source string from position 1 to the 
position number specified in this end-pos argument. 
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DESCRIPTION 

STR$LEFT extracts a substring from a source string and copies that substring 
into a destination string. STR$LEFT defines the substring by specifying the 
relative ending position in the source string. The relative starting position in 
the source string is 1. The source string is unchanged, unless it is also the 
destination string. 


This is a variation of STR$POS_EXTR. Other routines that may be used to 
extract and copy a substring are STR$RIGHT and STR$LEN_EXTR. 

CONDITION 

SS$_NORMAL 

Routine successfully completed. 

VALUES 

RETURNED 

STR$_ILLSTRPOS 

Routine successfully completed, except that an 
argument referenced a character position outside 
the specified string. A default value was used. 


STR$_ILLSTRSPE 

Routine successfully completed, except that the 
length of the substring was too long for the 
specified destination string. Default values were 
used. 


STR$_TRU 

String truncation warning. The fixed-length 
destination string could not contain all the 
characters copied from the source string. 

CONDITION 

VALUES 

SIGNALED 

STR$_FATINTERR 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 


STR$_ILLSTRCLA 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 


STR$_INSVIRMEM 

Insufficient virtual memory. STR$LEFT could not 
allocate heap storage for a dynamic or temporary 
string. 


EXAMPLE 


PROGRAM LEFT(INPUT, OUTPUT); 

{+> 

{ This PASCAL program demonstrates the use of 
{ STR$LEFT. This program reads in a source string 
{ and the ending position of a substring. 

{ It returns a substring consisting of all 
{ characters from the beginning (left) of the 

< source string to the ending position entered. 

<-} 

{+> 

< Declare the external procedure, STR$LEFT. 

<-> 

PROCEDURE STR$LEFT ('/.DESCR DSTSTR: VARYING 
[A] OF CHAR; SRCSTR 
VARYING [B] OF CHAR; ENDPOS : 

INTEGER); EXTERN; 
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<+> 

{ Declare the variables used by this program. 

{-> 

VAR 

SRC.STR : VARYING [256] OF CHAR; 

DST.STR : VARYING [256] OF CHAR; 

END.POS : INTEGER; 

<+> 

{ Begin the main program. Read the source string 
{ and ending position. Call STR$LEFT. Print the 
{ results. 

<-> 

BEGIN 

WRITELN('ENTER THE SOURCE STRING: '); 

READLN(SRC.STR); 

WRITELN('ENTER THE ENDING POSITION'); 

WRITELN('OF THE SUBSTRING: '); 

READLN(END.POS); 

STR$LEFT(DST.STR, SRC.STR, END.POS); 

WRITELN; 

WRITELN('THE SUBSTRING IS: '.DST.STR); 

END. 


This PASCAL example shows the use of STR$LEFT. The following is one 
sample of the output of this program: 

$ PASCAL LEFT 
$ LINK LEFT 
$ RUN LEFT 

ENTER THE SOURCE STRING: MAGIC CARPET 
ENTER THE ENDING POSITION OF 
THE SUBSTRING: 9 

THE SUBSTRING IS: MAGIC CAR 
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STR$LEN. 

-EXTR—Extract a Substring of a 
String 

STR$LEN_EXTR copies a substring of a source string into a 
destination string. 

FORMAT 

STR$LEN_EXTR dst-str ,src-str ,start-pos,length 

corresponding 
jsb entry point 

STR$LEN_EXTR_R8 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which STR$LEN_JEXTR copies the substring. The 
dst-str argument is the address of a descriptor pointing to the destination 
string. 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string from which STR$LEN_EXTR extracts the substring that it copies 
into the destination string. The src-str argument is the address of a descriptor 
pointing to the source string. 

start-pos 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Relative position in the source string at which the substring that STR$LEN_ 
EXTR copies starts. The start-pos argument is the address of a signed 
longword integer containing the starting position. 
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length 


VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Number of characters in the substring that STR$LEN__EXTR copies to the 
destination string. The length argument is the address of a signed longword 
integer containing the length of the substring. 


DESCRIPTION 

STR$LEN_EXTR extracts a substring from a source string and copies that 
substring into a destination string. 


STR$LEN_EXTR defines the substring by specifying the relative starting 
position in the source string and the number of characters to be copied. The 
source string is unchanged, unless it is also the destination string. 


If the starting position is less than 1, 1 is used. If the starting position is 
greater than the length of the source string, the null string is returned. If the 
length is less than 1, the null string is also returned. 


Other routines that may be used to extract and copy a substring are 

STR$RIGHT, STR$LEFT and STR$POS_EXTR. 

CONDITION 

SSS—NORMAL 

Routine successfully completed. 

VALUES 

RETURNED 

STR$_ILLSTRPOS 

STR$LEN_EXTR completed successfully, except 
that an argument referenced a character position 
outside the specified string. A default value was 
used. 


STR$_ILLSTRSPE 

STR$LEN_EXTR completed successfully, except 
that the length was too long for the specified 
string. Default values were used. 


STR$_NEGSTRLEN 

STR$LEN_EXTR completed successfully, except 
that length contained a negative value. Zero was 
used. 


STR$_TRU 

String truncation warning. The fixed-length 
destination string could not contain all the 
characters copied from the source string. 

CONDITION 

VALUES 

SIGNALED 

STR$_FATINTERR 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 


STR$_ILLSTRCLA 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 


STR$_INSVIRMEM 

Insufficient virtual memory. STR$LEN_EXTR 
could not allocate heap storage for a dynamic or 
temporary string. 


RTL-803 






Run-Time Library Routines 

STR$LEN_EXTR 


EXAMPLE 

CHARACTER*131 IN.STRING 

CHARACTER*1 FRONT.CHAR 

CHARACTER*1 TAIL.CHAR 

INTEGER STR$LEN_EXTR, STR$REPLACE, STR$TRIM 
INTEGER FRONT.POSITION. TAIL.POSITION 
10 WRITE (6, 800) 

800 FORMAT (' Enter a string, 131 characters or less:',$) 

READ (5, 900, END=200) IN.STRING 

900 FORMAT (A) 

ISTATUS = STR$TRIM (IN.STRING. IN.STRING, LENGTH) 

DO 100 I - 1, LENGTH/2 
FRONT.POSITION = I 
TAIL.POSITION = LENGTH +1-1 

ISTATUS = STR$LEN_EXTR ( FRONT.CHAR, IN.STRING, FRONT.POSITION, 
A '/.REF (1) ) 

ISTATUS = STR$LEN_EXTR ( TAIL.CHAR, IN.STRING, TAIL.POSITION. 

A '/.REF (1) ) 

ISTATUS = STRSREPLACE ( IN.STRING. IN.STRING, FRONT.POSITION, 

A FRONT.POSITION, TAIL.CHAR) 

ISTATUS = STR$REPLACE ( IN.STRING, IN.STRING, TAIL.POSITION. 

A TAIL.POSITION. FRONT.CHAR) 

100 CONTINUE 

WRITE (6. 901) IN.STRING 

901 FORMAT (' Reversed string is : './.lX.A) 

GOTO 10 

200 CONTINUE 

END 


This FORTRAN program accepts a string as input and writes the string in 
reverse order as output. This program continues to prompt for input until 
CTRL/Z is pressed. One sample of the output generated by this program is 
as follows: 

$ FORTRAN REVERSE 
$ LINK REVERSE 
$ RUN REVERSE 

Enter a string, 131 characters or less: African elephants often have 
flat feet. 

Reversed string is : 

.teef talf evah netfo stnahpele nacirfA 
Enter a string, 131 characters or less: CTRL/Z 

$ 
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STR$M ATCH—WILD—Match Wildcard 

Specification 


STR$MATCH_WILD is used to compare a pattern string that 
includes wildcard characters with a candidate string. It returns a 
condition value of STR$_MATCH if the strings match and STR$_ 
NOMATCH if they do not match. 

FORMAT 

STR$MATCH_WILD cand-str ,pattern-str 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

cand-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String to which the pattern string is compared. The cand-str argument is the 
address of a descriptor pointing to the candidate string. 


pattern-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String containing wildcard characters. The pattern-str argument is the 
address of a descriptor pointing to the pattern string. The wildcards in 
the pattern string are translated when STR$M ATCH—WILD searches the 
candidate string to determine if it matches the pattern string. 

DESCRIPTION 

STR$MATCH—WILD translates wildcard characters and searches the 
candidate string to determine if it matches the pattern string. The pattern 
string may contain either one or both of the two wildcard characters, asterisk 
(*) and percent (%). The asterisk character is mapped to one or more 
characters. The percent character is mapped to only one character. 

The two wildcard characters that may be used in the pattern string may be 
used only as wildcards. If the candidate string contains an asterisk or percent 
character, the condition STR$_NOMATCH is returned, because the wildcard 
characters are never translated literally. 
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CONDITION 

VALUES 

RETURNED 

STR$_MATCH 

STR$_NOMATCH 

The candidate string and the pattern string match. 

The candidate string and the pattern string do not 
match. 

CONDITION 

VALUE 

SIGNALED 

STR$_ILLSTRCLA 

Illegal string class. Severe error. The descriptor 
of cand-str and/or pattern-str contains a class 
code that is not supported by the VAX Procedure 
Calling and Condition Handling Standard. 

EXAMPLE 


/* 

* Example program using STR$MATCH_WILD. (VAX PL/I V2.3) 

* 

* The following program reads in a master pattern string and then 

* compares that to input strings until it reaches the end of the 

* input file. For each string comparison done, it will print 

* either 'Matches pattern string' or 'Doesn't match pattern string'. 
*/ 

declare strlmatch.wild 

external entry (character(*) varying, character(*) varying) 
returns (bit(l)); 
example: procedure options(main); 

del pattern.string character(80) varying; 
del test.string character(80) varying; 
on endfile(sysin) stop; 
put skip; 

get list(pattern_string) options(prompt('Pattern string> ')); 
do while( '1'b ); 

get skip list(test.string) options(prompt('Test string> ')); 
if str$match_wild(test_string,pattern_8tring) 

then put skip list('Matches pattern string'); 
else put skip list('Doesn''t match pattern string'); 

end; 

end; 


This PL/I program demonstrates the use of STR$MATCH_WILD. The output 
generated by this program is as follows: 

$ PLI MATCH 
$ LINK MATCH 
$ RUN MATCH 

Pattern string> 'Must match me exactly.' 

Test string> 'Will this work? Must match me exactly.' 

Doesn't match pattern string 

Test string> 'must match me exactly' 

Doesn't match pattern string 

Test string> 'must match me exactly.' 

Doesn't match pattern string 

Test string> 'Must match me exactly' 

Doesn't match pattern string 

Test String> 'Must match me exactly.' 

Matches pattern string 
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STR$MUL—Multiply Two Decimal Strings 

STR$MUL multiplies two decimal strings. 


FORMAT STR$MUL asign ,aexp , adigits , bsign ,bexp ,bdigits 

,csign ,cexp ,cdigits 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


ARGUMENTS 


asign 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Sign of the first operand. The asign argument is the address of an unsigned 
longword containing the first operand's sign. Zero is considered positive; 1 is 
considered negative. 


aexp 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Power of 10 by which adigits has to be multiplied to get the absolute value 
of the first operand. The aexp argument is the address of a signed longword 
integer containing this exponent. 


adigits 

VMS Usage: char_string 
type: num. string, unsigned 

access: read only 

mechanism: by descriptor 

First operand's numeric string. The adigits argument is the address of a 
descriptor pointing to the numeric string of the first operand. The string must 
be an unsigned decimal number. 


bsign 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 

Sign of the second operand. The bsign argument is the address of an 
unsigned longword containing the sign of the second operand. Zero is 
considered positive; 1 is considered negative. 
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bexp 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Power of 10 by which bdigits has to be multiplied to get the absolute 
value of the second operand. The bexp argument is the address of a signed 
longword integer containing this exponent. 

bdigits 

VMS Usage: char_string 
type: num. string, unsigned 

access: read only 

mechanism: by descriptor 

Second operand's numeric string. The bdigits argument is the address of a 
descriptor pointing to the second operand's numeric string. The string must 
be an unsigned decimal number. 

csign 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Sign of the result. The csign argument is the address of a signed longword 
integer containing the sign of the result. Zero is considered positive; 1 is 
considered negative. 

cexp 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Power of 10 by which cdigits has to be multiplied to get the absolute value 
of the result. The cexp argument is the address of a signed longword integer 
containing this exponent. 

cdigits 

VMS Usage: char_string 
type: num. string, unsigned 

access: write only 

mechanism: by descriptor 

Result's numeric string. The cdigits argument is the address of a descriptor 
pointing to the numeric string of the result. The string will be an unsigned 
decimal number. 

DESCRIPTION 

STR$MUL multiplies two decimal strings. The numbers to be multiplied are 
passed to STR$MUL in three parts: (1) the numeric string, (2) the power 
of 10 needed to obtain the absolute value, and (3) the sign of the decimal 
number. The result of the multiplication is also returned in those three parts. 
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CONDITION 

VALUES 

RETURNED 

SS$_NORMAL 

STR$_TRU 

Routine successfully completed. 

String truncation warning. The fixed-length 
destination string could not contain all the 
characters. 

CONDITION 

LIB$_INVARG 

Invalid argument. 

VALUES 

STR$_FATINTERR 

Fatal internal error. An internal consistency check 

SIGNALED 


has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 


STR$_ILLSTRCLA 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 


STR$_INSVIRMEM 

Insufficient virtual memory. STR$MUL could not 
allocate heap storage for a dynamic or temporary 
string. 


STR$_WRONUMARG 

Wrong number of arguments. 


EXAMPLE 


100 


This example program uses 
STR$MUL to multiply two decimal 
strings (A and B) and place the 
results in a third decimal string, 
(C) 


ASIGN*/, = 1*/. 

AEXPy. = 3'/, 

ADIGITS$ = *1' 

BSIGN'/, = oy. 

BEXP'/. = -4*/. 

BDIGITS$ = '2' 

CSIGN'/, = oy. 
cEXpy. = oy. 

CDIGITS$ = 'O' 

PRINT "A = ASIGN*/.; AEXP*/.; ADIGITS$ 

PRINT "B = BSIGN'/.; BEXP*/.; BDIGITS$ 

CALL STR$MUL (ASIGN*/., AEXP'/., ADIGITS$, k 

BSIGN*/., BEXP*/., BDIGITS$ , k 
CSIGN*/., CEXP%. CDIGITS$) 
PRINT "C = "; CSIGN*/.; CEXP'/.; CDIGITS$ 

999 END 


This BASIC example uses STR$MUL to multiply two decimal strings, where 
the following values apply: 

A = -1000 (ASIGN = 1, AEXP = 3, ADIGITS = 'l') 

B = .0002 (BSIGN = 0, BEXP = -4, BDIGITS = ' 2 ') 
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Listed below is the output generated by this program; note that the decimal 
value C equals -.2 (CSIGN = 1, CEXP = -1, CDIGITS = 2). 


A = 1 3 1 
B = 0 -4 2 
C = 1 -1 2 
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STR$POSITIOIM—Return Relative Position 

of Substring 


STR$POSITION searches for the first occurrence of a single 
substring within a source string. If STR$POSITION finds the 
substring, it returns the relative position of that substring. If the 
substring is not found, STR$POSITION returns a zero. 

FORMAT 

STR$POSITION src-str , sub-str[,start-pos] 

corresponding 
jsb entry point 

STR$POSITION_R6 

RETURNS 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Relative position of the first character of the substring. Zero is the value 
returned if STR$POSITION did not find the substring. 

ARGUMENTS 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string within which STR$POSITION searches for the substring. The 
src-str argument is the address of a descriptor pointing to the source string. 


sub-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Substring for which STR$POSITION searches. The sub-str argument is the 
address of a descriptor pointing to the substring. 


start-pos 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Relative position in the source string at which STR$POSITION begins the 
search. The start-pos argument is the address of a signed longword integer 
containing the starting position. Although this is an optional argument, it is 
required if you are using the JSB entry point. 

If start-pos is not supplied, STR$POSITION starts the search at the first 
character position of src-str. 


RTL-811 









Run-Time Library Routines 

STR$POSITION 


DESCRIPTION STR$POSITION returns the relative position of the first occurrence of a 

substring in the source string. The value returned is an unsigned integer 
longword. The relative character positions are numbered 1, 2, 3, and so on. 
Zero indicates that the substring was not found. 

If the substring has a zero length, the minimum value of start-pos and (the 
length of src-str plus one) is returned by STR$POSITION. 

If the source string has a zero length and the substring has a nonzero length, 
zero is returned, indicating that the substring was not found. 


CONDITION STR$_ILLSTRCLA 

VALUE 

SIGNALED 


Illegal string class. The class code found in the 
string class field of a descriptor is not a string class 
code allowed by the Vax Procedure Calling and 
Condition Handling Standard. 


EXAMPLE 


PROGRAM POSITION(INPUT,OUTPUT); 

{+> 

{ This example uses STR$P0SITI0N to determine 
{ the position of a the first occurence of 

< a substring (SUBSTRING) within a source 
i string (STRING1) after the starting 

< position (START). 

< 

{ First, declare the external function. 

<-y 

FUNCTION STR$P0SITI0N(SRCSTR : VARYING [A] 

OF CHAR; SUBSTR : VARYING [B] OF CHAR; 

STARTPOS : INTEGER) : INTEGER; EXTERN; 

{+> 

{ Declare the variables used in the main program. 

{-> 

VAR 

STRING1 : VARYING [256] OF CHAR; 

SUBSTRING : VARYING [256] OF CHAR; 

START : INTEGER; 

RET.STATUS : INTEGER; 

{♦> 

{ Begin the main program. Read the string and substring. 

{ Set START equal to i to begin looking for the substring 
{ at the beginning of the source string. Call STR$P0SITI0N 
{ and print the result. 

<-> 

BEGIN 

WRITELNCENTER THE STRING: '); 

READLN(STRING1); 

WRITELN('ENTER THE SUBSTRING: '); 

READLN(SUBSTRING); 

START := 1; 

RET.STATUS := STR$P0SITI0N(STRING1, SUBSTRING. START); 
WRITELN(RET.STATUS); 

END. 


This PASCAL program demonstrates the use of STR$POSITION. If you run 
this program and set STRING 1 equal to KITTEN and substring equal to TEN, 
the value of RET_STATUS will be 4. 
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STR$POS. 

-EXTR—Extract a Substring of a 
String 

STR$POS_EXTR copies a substring of a source string into a 
destination string. 

FORMAT 

STR$POS_EXTR dst-str,src-str, start-pos ,end-pos 

corresponding 
jsb entry point 

STR$POS_EXTR_R8 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 


dst-str 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
write only 
by descriptor 


Destination string into which STR$POS_EXTR copies the substring. The 
dst-str argument is the address of a descriptor pointing to the destination 
string. 


src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string from which STR$POS_EXTR extracts the substring that it copies 
into the destination string. The src-str argument is the address of a descriptor 
pointing to the source string. 


start-pos 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference for CALL entry point, by value for JSB entry 
point 

Relative position in the source string at which the substring that STR$POS_ 
EXTR copies starts. The start-pos argument is the address of a signed 
longword integer containing the starting position. 
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end-pos 

VMS Usage: 
type: 
access: 
mechanism: 


longword_signed 
longword integer (signed) 
read only 

by reference for CALL entry point, by value for JSB entry 
point 


Relative position in the source string at which the substring that STR$POS_ 
EXTR copies ends. The end-pos argument is the address of a signed 
longword integer containing the ending position. 


DESCRIPTION STR$POS_JEXTR extracts a substring from a source string and copies the 

substring into a destination string. STR$POS_EXTR defines the substring by 
specifying the relative starting and ending positions in the source string. The 
source string is unchanged, unless it is also the destination string. 

If the starting position is less than 1 then 1 is used. If the starting position is 
greater than the length of the source string, the null string is returned. If the 
ending position is greater than the length of the source string, the length of 
the source string is used. 

Other routines that may be used to copy a substring are STR$LEFT, 
STR$RIGHT and STR$LEN_EXTR. 


CONDITION SSS—NORMAL 

VALUES STR$_ILLSTRPOS 

RETURNED 

STR$_ILLSTRSPE 

STR$_TRU 


Routine successfully completed. 

Routine successfully completed, except that an 
argument referenced a character position outside 
the specified string. A default value was used. 

Routine successfully completed, except that end- 
pos was less than start-pos. Default values were 
used. 

String truncation warning. The fixed-length 
destination string could not contain all the 
characters copied from the source string. 


CONDITION STR$_FATINTERR 

VALUES 

SIGNALED 

STR$_ILLSTRCLA 


STR$_INSVIRMEM 


Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 

Insufficient virtual memory. STR$POS_EXTR 
could not allocate heap storage for a dynamic or 
temporary string. 
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EXAMPLE 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

FTTY D F 80 TTY 

C* Initialize source string and position 
C MOVE '7 SW Ave'SOURCE 8 

C Z-ADD3 BEGPOS 90 

C Z-ADD4 ENDPOS 90 

C POS.EXTR EXTRN'STR$POS_EXTR' 


C* Extract the 2 character string beginning 


C 

C 

C 

C 

C 


CALL POS.EXTR 
PARMD DEST 

PARMD SOURCE 

PARM BEGPOS 

PARM ENDPOS 


at position 3 
2 


RL 

RL 


C* Display on the terminal the extracted string 
C DEST DSPLYTTY 

C SETON LR 


The RPG II program above displays the string 'SW' on the terminal. 
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STR$PREFIX—Prefix a String 



STR$PREFIX inserts a source string at the beginning of a destination 
string. The destination string must be dynamic or varying. 

FORMAT 

STR$PREFIX dst-str ,src-str 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string (dynamic or varying); STR$PREFIX copies the source string 
into the beginning of this destination string. The dst-str argument is the 
address of a descriptor pointing to the destination string. 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string which STR$PREFIX copies into the beginning of the destination 
string. The src-str argument is the address of a descriptor pointing to the 
source string. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Routine successfully completed 

STR$_TRU String truncation warning. The fixed-length 

destination string could not contain all of the 
characters. 
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CONDITION STR$_FATINTERR 

VALUES 

SIGNALED 

STR$_ILLSTRCLA 


STR$_INSVIRMEM 


Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 

Insufficient virtual memory. STRSPREFIX could not 
allocate heap storage for a dynamic or temporary 
string. 


EXAMPLE 


This example uses STRSPREFIX to 
prefix a destination string (D$) 
with a source string ('ABCD'). 


EXTERNAL INTEGER FUNCTION STRSPREFIX 
DS = 'EFG' 

STATUS*/. = STRSPREFIX (DS. 'ABCD') 

PRINT DS 

END 


These BASIC statements set D$ equal to 'ABCDEFG'. 
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STR$RECIP—Reciprocal of a Decimal 



String 

STR$RECIP takes the reciprocal of the first decimal string to the 
precision limit specified by the second decimal string and returns the 
result as a decimal string. 

FORMAT 

STR$RECIP asign ,aexp ,adigits ,bsign ,bexp ,bdigits 
,csign ,cexp ,cdigits 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

asign 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Sign of the first operand. The asign argument is the address of an unsigned 
longword containing the first operand's sign. Zero is considered positive; 1 is 
considered negative. 

aexp 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Power of 10 by which adigits has to be multiplied to get the absolute value 
of the first operand. The aexp argument is the address of a signed longword 
integer containing this exponent. 

adigits 

VMS Usage: char—string 
type: num. string, unsigned 

access: read only 

mechanism: by descriptor 

First operand's numeric string. The adigits argument is the address of a 
descriptor pointing to the first operand's numeric string. The string must be 
an unsigned decimal number. 
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bsign 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Sign of the second operand. The bsign argument is the address of an 
unsigned longword containing the sign of the second operand. Zero is 
considered positive; 1 is considered negative. 


bexp 

VMS Usage: 
type: 
access: 
mechanism: 


longword_signed 
longword integer (signed) 
read only 
by reference 

Power of 10 by which bdigits has to be multiplied to get the absolute 
value of the second operand. The bexp argument is the address of a signed 
longword integer containing this exponent. 


bdigits 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
num. string, unsigned 
read only 
by descriptor 

Second operand's numeric string. The bdigits argument is the address of a 
descriptor pointing to the second operand's numeric string. The string must 
be an unsigned decimal number. 


csign 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Sign of the result. The csign argument is the address of a signed longword 
integer containing the result's sign. Zero is considered positive; 1 is 
considered negative. 


cexp 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Power of 10 by which cdigits has to be multiplied to get the absolute value 
of the result. The cexp argument is the address of a signed longword integer 
containing this exponent. 
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cdigits 

VMS Usage: char_string 
type: num. string, unsigned 

access: write only 

mechanism: by descriptor 

Result's numeric string. The cdigits argument is the address of a descriptor 
pointing to the result's numeric string. The string will be an unsigned decimal 
number. 


CONDITION 

VALUES 

RETURNED 

SS$_NORMAL 

STR$_TRU 

Routine successfully completed. 

String truncation warning. The fixed-length 
destination string could not contain all of the 
characters. 

CONDITION 

STR$_DIVBY_ZER 

Division by zero. 

VALUES 

LIB$_INVARG 

Invalid argument. 

SIGNALED 

STR$_FATINTERR 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 


STR$_ILLSTRCLA 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 


STR$_INSVIRMEM 

Insufficient virtual memory. STR$RECIP could not 
allocate heap storage for a dynamic or temporary 
string. 


STR$_WRONUMARG 

Wrong number of arguments. 


EXAMPLE 


100 


This example program uses 
STR$RECIP to find the reciprocal of 
the first decimal string (A) to the 
precision specified in the second 
decimal string (B), and place the 
result in a third decimal string (C). 


ASIGNY, = 1% 
AEXPV. = 3% 
ADIGITS$ = * 1 * 
BSIGN’/, = oy. 
BEXPy. = -4% 
BDIGITS$ = '2' 

csiGNy, * oy. 
cEXpy. = oy. 

CDIGITS! = 'O' 


RTL-820 










Run-Time Library Routines 

STR$RECIP 


PRINT "A = ASIGN'/,; AEXP*/.; ADIGITS$ 

PRINT "B = "; BSIGN*/,; BEXP'/.; BDIGITS$ 

CALL STRSRECIP (ASIGN*/., AEXP*/., ADIGITS$, & 

BSIGN'/., BEXP'/., BDIGITS$, & 

CSIGN'/,, CEXP'/,, CDIGITS$) 
PRINT "C = "; CSIGN*/.; CEXP'/.; CDIGITS$ 

999 END 


This BASIC example uses STR$RECIP to find the reciprocal of A to the 
precision level specified in B. 

The following values apply: 

A = -1000 (ASIGN = 1, AEXP = 3, ADIGITS = T) 

B = .0002 (BSIGN = 0, BEXP = -4, BDIGITS = ' 2 ') 

The output generated by this program is as follows, yielding a decimal value 
of C equal to -.001. 

a = 1 3 1 

B = 0 -4 2 
C = 1 -3 1 
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STR$REPLACE—Replace a Substring 



STR$REPLACE copies a source string to a destination string, 
replacing part of the string with another string. The substring to be 
replaced is specified by its starting and ending positions. 

FORMAT 

STR$REPLACE dst-str ,src-str ,start-pos ,end-pos 
,rpl-str 

corresponding 
jsb entry point 

STR$REPLACE_R8 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which STR$REPLACE writes the new string created 
when it replaces the substring. The dst-str argument is the address of a 
descriptor pointing to the destination string. 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string. The src-str argument is the address of a descriptor pointing to 
the source string. 

start-pos 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference for CALL entry point, by value for JSB entry 
point 

Position in the source string at which the substring which STR$REPLACE 
replaces begins. The start-pos argument is the address of a signed longword 
integer containing the starting position. The position is relative to the start of 
the source string. 
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end-pos 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference for CALL entry point, by value for JSB entry 
point 

Position in the source string at which the substring which STR$REPLACE 
replaces ends. The end-pos argument is the address of a signed longword 
integer containing the ending position. The position is relative to the start of 
the source string. 

rpl-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Replacement string with which STR$REPLACE replaces the substring. The 
rpl-str argument is the address of a descriptor pointing to this replacement 
string. 

DESCRIPTION 

STR$REPLACE copies a source string to a destination string, replacing part of 
the string with another string. The substring to be replaced is specified by its 
starting and ending positions. 

If the starting position is less than 1, 1 is used. If the ending position is 
greater than the length of the source string, the length of the source string 
is used. If the starting position is greater than the ending position, the 
overlapping portion of the source string will be copied twice. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Routine successfully completed. 

STR$_ILLSTRPOS Routine successfully completed, but an argument 

referenced a character position outside the 
specified string. A default value was used. 

STR$_ILLSTRSPE Routine successfully completed, but end-pos was 

less than start-pos or length was too long for the 
specified string. Default values were used. 

STR$_TRU String truncation warning. The fixed-length 

destination string could not contain all of the 


characters. 
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CONDITION STR$_FATINTERR 

VALUES 

SIGNALED 

STR$_ILLSTRCLA 


STR$_INSVIRMEM 


Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 

Insufficient virtual memory. STRSREPLACE 
could not allocate heap storage for a dynamic or 
temporary string. 


EXAMPLE 


! This examples uses STR$REPLACE to 
! replace all characters from the starting 
! position (2*/,) to the ending position (3*/,) 

! with characters from the replacement string 
! ('XYZ 1 ). 

EXTERNAL INTEGER FUNCTION STR$REPLACE 
D$ = 'ABCD' 

STATUS*/, = STRSREPLACE (D$, D$, 2%, 3*/., 'XYZ') 
PRINT D$ 

END 


These BASIC statements set D$ equal to 'AXYZD'. 
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STR$RIGHT—Extract a Substring of a 

String 


STR$RIGHT copies a substring of a source string into a destination 
string. 

FORMAT 

STR$RIGHT dst-str,src-str,start-pos 

corresponding 
jsb entry point 

STR$RIGHT_R8 

RETURNS 

VMS Usage: cond_value 

type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 


dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which STR$RIGHT copies the substring. The dst-str 
argument is the address of a descriptor pointing to the destination string. 


src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string from which STR$RIGHT extracts the substring that it copies 
into the destination string. The src-str argument is the address of a descriptor 
pointing to the source string. 


start-pos 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference for CALL entry point, by value for JSB entry 
point 

Relative position in the source string at which the substring that STR$RIGHT 
copies starts. The start-pos argument is the address of a signed longword 
integer containing the starting position. 
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DESCRIPTION 

STR$RIGHT extracts a substring from a source string and copies that 
substring into a destination string. STR$RIGHT defines the substring by 
specifying the relative starting position. The relative ending position is equal 
to the length of the source string. The source string is unchanged, unless it is 
also the destination string. 


If the starting position is less than 2, the entire source string is copied. If the 
starting position is greater than the length of the source string, a null string is 
copied. 


This is a variation of STR$POS_EXTR. Other routines that may be used to 
extract and copy a substring are STR$LEFT and STR$LEN_EXTR. 

CONDITION 

SS$_NORMAL 

Routine successfully completed. 

VALUES 

RETURNED 

STR$_ILLSTRPOS 

Routine successfully completed, except that an 
argument referenced a character position outside 
the specified string. A default value was used. 


STRS—TRU 

String truncation warning. The fixed-length 
destination string could not contain all the 
characters copied from the source string. 

CONDITION 

VALUES 

SIGNALED 

STR$_FATINTERR 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 


STR$_ILLSTRCLA 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 


STR$_INSVIRMEM 

Insufficient virtual memory. STRSRIGHT could not 
allocate heap storage for a dynamic or temporary 
string. 


EXAMPLE 


PROGRAM RIGHT(INPUT, OUTPUT); 

{♦> 

< This example uses STR$RIGHT to extract a substring 
{ from a specified starting position (START_P0S) to 
{ the end (right side) of a source string (SRC_STR) 

< and write the result in a destination string (DST_STR). 

< 

{ First, declare the external procedure. 

{-> 

PROCEDURE STR$RIGHT(XDESCR DSTSTR: VARYING 

[A] OF CHAR; SRCSTR : VARYING [B] OF CHAR; 
STARTPOS : INTEGER); EXTERN; 

{*> 

{ Declare the variables used in the main program. 

{-> 

VAR 

SRC.STR : VARYING [256] OF CHAR; 

DST.STR : VARYING [256] OF CHAR; 

START.POS : INTEGER; 
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{ Begin the main program. Read the source string 
{ and starting position. Call STR$RIGHT to extract 
{ the substring. Print the result. 

{-> 

BEGIN 

WRITELN('ENTER THE SOURCE STRING: '); 

READLN(SRC_STR); 

WRITELN CENTER THE STARTING POSITION'); 

WRITELN('OF THE SUBSTRING: '); 

READLN(START.POS); 

STR$RIGHT(DST_STR, SRC.STR, START.POS); 

WRITELN; 

WRITELN('THE SUBSTRING IS: \DST_STR); 

END. 


This PASCAL program uses STR$RIGHT to extract a substring from a 
specified starting position (START—POS) to the end of the source string. One 
sample of the output is as follows: 

$ RUN RIGHT 

ENTER THE SOURCE STRING: BLUE PLANETS ALWAYS HAVE PURPLE PLANTS 

ENTER THE STARTING POSITION 

OF THE SUBSTRING: 27 

THE SUBSTRING IS: URPLE PLANTS 
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STR$ROUND—Round or Truncate a 

Decimal String 

STR$ROUND rounds or truncates a decimal string to a specified 
number of significant digits and places the result in another decimal 
string. 


FORMAT 

STR$ROUND places, trunc-flg,asign ,aexp ,adigits 
,csign ,cexp ,cdigits 

RETURNS 

VMS Usage: 

cond_value 


type: 

longword (unsigned) 


access: 

write only 


mechanism: 

by value 


ARGUMENTS 


places 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Maximum number of decimal digits that STR$ROUND retains in the result. 
The places argument is the address of a signed longword integer containing 
the number of decimal digits. 


trunc-flg 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Function flag. Zero indicates that the decimal string is rounded; 1 indicates 
that it is truncated. The trunc-flg argument is the address of an unsigned 
longword containing this function flag. 


asign 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Sign of the first operand. The asign argument is the address of an unsigned 
longword string containing this sign. A value of zero indicates that the 
number is positive, while a value of 1 indicates that the number is negative. 
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CONDITION 

VALUES 

RETURNED 


aexp 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Power of 10 by which adigits has to be multiplied to get the absolute value 
of the first operand. The aexp argument is the address of a signed longword 
integer containing this exponent. 


adigits 

VMS Usage: char_string 
type: num. string, unsigned 

access: read only 

mechanism: by descriptor 

First operand's numeric string. The adigits argument is the address of a 
descriptor pointing to this numeric string. The string must be an unsigned 
decimal number. 


csign 

VMS Usage: 
type: 
access: 
mechanism: 


longword_signed 
longword integer (signed) 
write only 
by reference 


Sign of the result. The csign argument is the address of a signed longword 
integer containing the result's sign. A value of zero indicates that the number 
is positive, while a value of 1 indicates that the number is negative. 


cexp 

VMS Usage: 
type: 
access: 
mechanism: 


longword_signed 
longword integer (signed) 
write only 
by reference 


Power of 10 by which cdigits has to be multiplied to get the absolute value 
of the result. The cexp argument is the address of a signed longword integer 
containing this exponent. 


cdigits 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
num. string, unsigned 
write only 
by descriptor 


Result's numeric string. The cdigits argument is the address of a descriptor 
pointing to this numeric string. The string will be an unsigned decimal 
number. 


SS$_NORMAL Routine successfully completed. 

STR$_TRU String truncation warning. The fixed-length 

destination string could not contain all of the 
characters. 
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CONDITION LIB$_INVARG 

VALUES STR$_FATINTERR 

SIGNALED 

STR$_ILLSTRCLA 

STR$_INSVIRMEM 

STR$_WRONUMARG 


Invalid argument. 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 

Insufficient virtual memory. STR$ROUND could not 
allocate heap storage for a dynamic or temporary 
string. 

Wrong number of arguments. 


EXAMPLE 


100 


This example shows the difference between 
the values obtained when rounding or truncating 
a decimal string. 


asign 7 . = oy. 

AEXP% = -4'/. 

ADIGITSI * '9999998' 

CSIGNX = 0'/. 

cEXpy. = oy. 

CDIGITS$ * 'O' 

PRINT "A = ASIGN'/,; AEXP'/.; ADIGITSl 


First, call STR$R0UND to round the value of A. 


CALL STRIROUND (3*/., 0%, ASIGN'/., AEXP'/., ADIGITS$, & 

CSIGN'/., CEXpy., CDIGITS$) 

PRINT "ROUNDED: C * CSIGN'/.; CEXP%; CDIGITS$ 


Now, call STR$R0UND to truncate the value of A. 


CALL STR$R0UND 

PRINT "TRUNCATED: 
999 END 


(3%, IX, ASIGN'/., AEXP%, ADIGITS$, & 
CSIGN'/., CEXPy.. CDIGITS$) 

C = "; CSIGN'/.; CEXP'/.; CDIGITS$ 


This BASIC example uses STR$ROUND to first round and then truncate 
the value of A to the number of decimal places specified by places. The 
following values apply: 

A = 999.9998 (ASIGN = 1, AEXP = -4, ADIGITS = '9999998') 

Listed below is the output generated by this program; note that the decimal 
value of C equals 1000 when rounded, and 999 when truncated. 

A = 1 -4 9999998 

ROUNDED: C = 0 1 100 
TRUNCATED: C = 0 0 999 
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STR$TR AIM SLATE—Translate Matched 



STR$TRANSLATE successively compares each character in a 
source string to all characters in a match string. If a source character 
has a match, the destination character is taken from the translate 
string. Otherwise, STR$TRANSLATE moves the source character 
to the destination string. 

FORMAT 

STR$TRANSLATE dst-str ,src-str, trans-str ,match- 

str 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string. The dst-str argument is the address of a descriptor 
pointing to the destination string. 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string. The src-str argument is the address of a descriptor pointing to 
the source string. 

trans-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Translate string. The trans-str argument is the address of a descriptor 
pointing to the translate string. 

match-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Match string. The match-str argument is the address of a descriptor pointing 
to the match string. 
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DESCRIPTION 

STR$TRANSLATE successively compares each character in a source string 
to all characters in a match string. If a source character matches any of the 
characters in the match string, STR$TRANSLATE moves a character from 
the translate string to the destination string. Otherwise, STR$TRANSLATE 
moves the character from the source string to the destination string. 


The character taken from the translate string has the same relative position 
as the matching character had in the match string. When a character appears 
more than once in the match string, the position of the leftmost occurrence of 
the multiply defined character is used to select the translate string character. 

If the translate string is shorter than the match string and the matched 
character position is greater than the translate string length, the destination 
character is a space. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL 

STR$_TRU 

Routine successfully completed. 

String truncation warning. The fixed-length 
destination string could not contain all of the 
characters. 

CONDITION 

VALUES 

SIGNALED 

STR$_FATINTERR 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 


STR$_ILLSTRCLA 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 


STR$_INSVIRMEM 

Insufficient virtual memory. STR$TRANSLATE 
could not allocate heap storage for a dynamic or 
temporary string. 


EXAMPLE 


10 


This example program uses STR$TRANSLATE to 
translate all characters of a source string 
from uppercase to lowercase characters. 


EXTERNAL INTEGER FUNCTION STR$TRANSLATE(STRING.STRING,STRING.STRING) 
T0$='abcdefghijklmnopqrstuvwxyz' 

FR0M$='ABCDEFGHIJKLMNOPQRSTUVWXYZ' 

X% = STR$TRANSLATE(0UT$,'TEST',T0$,FR0M$) 

PRINT 'Status = ' ;x'/. 

PRINT 'Resulting string = ';out$ 

32767 END 


This BASIC example translates uppercase letters to lowercase letters, thus 
performing the same function as STR$UPCASE. 

The output generated by this example is as follows: 
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$ RUN TRANSLATE 
Status = 1 

Resulting string = test 
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A more practical although more complicated use for STR$TRANSLATE would 
be to encrypt data by translating the characters to obscure combinations of 
numbers and alphabetic characters. 
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STR$TRIM—Trim Trailing Blanks and Tabs 



STR$TRIM copies a source string to a destination string and deletes 
the trailing blank and tab characters. 

FORMAT 

STR$TR 1M dst-str,src-str[, out-len] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which STR$TRIM copies the trimmed string. The 
dst-str argument is the address of a descriptor pointing to the destination 
string. 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string which STR$TRIM trims and then copies into the destination 
string. The src-str argument is the address of a descriptor pointing to the 
source string. 

out-len 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Number of bytes that STR$TRIM has written into dst-str, not counting 
padding in the case of a fixed-length string. The out-len argument is the 
address of an unsigned word into which STR$TRIM writes the length of 
the output string. If the input string is truncated to the size specified in the 
dst-str description, out-len is set to this size. Therefore, out-len can always 
be used by the calling program to access a valid substring of dst-str. 
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CONDITION 

VALUES 

RETURNED 


CONDITION 

VALUES 

SIGNALED 


SS$_NORMAL Routine successfully completed. 

STR$_TRU String truncation warning. The fixed-length 

destination string could not contain all the 
characters. 


STR$_FATINTERR 


STR$_ILLSTRCLA 


STR$_INSVIRMEM 


Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 

Insufficient virtual memory. STR$TRIM could not 
allocate heap storage for a dynamic or temporary 
string. 
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STR$UPCASE—Convert String to All 



Uppercase Characters 

STR$UPCASE converts a source string to uppercase and writes 
the converted string into the destination string. When you need 
to compare characters without regard to case, you can first 
use STR$UPCASE to convert both characters to uppercase. 
STR$UPCASE converts all characters in the multinational character 
set. 

FORMAT 

STR$UPCASE dst-str,src-str 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which STR$UPCASE writes the string it has converted 
to uppercase. The dst-str argument is the address of a descriptor pointing to 
the destination string. 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string that STR$UPCASE converts to uppercase. The src-str argument 
is the address of a descriptor pointing to the source string. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Routine successfully completed. 

STR$_TRU String truncation warning. The fixed-length 

destination string could not contain all the 
characters. 
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CONDITION STR$_FATINTERR 

VALUES 

SIGNALED 

STR$_ILLSTRCLA 


STR$_INSVIRMEM 


Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Illegal string class. The class code found in the 
class field of a descriptor is not a string class 
code allowed by the VAX Procedure Calling and 
Condition Handling Standard. 

Insufficient virtual memory. STR$UPCASE could 
not allocate heap storage for a dynamic or 
temporary string. 


EXAMPLES 


This example uses STR$UPCASE 
to convert all characters in 
the source string (SRC$) to 
uppercase and write the result 
in the destination string (DST$). 


SRC$ = 'abed' 

PRINT "SRC$ =";SRC$ 

CALL STR$UPCASE (DST$, SRC$) 
PRINT "DST$ =";DST$ 

END 


This BASIC program generates the following output: 

SCR$ =abcd 
DST$ =ABCD 


0I1I2I3I4I6I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

FTTY D F 80 TTY 

C* Initialize string to be converted to upper case 
C MOVE 'rep head'HEAD 8 

C UPCASE EXTRN'STR$UPCASE' 

C* Convert the string to upper case 
C CALL UPCASE 

C PARMD RESULT 8 

C PARMD HEAD 

C* Display on the terminal the string in upper case 
C RESULT DSPLYTTY 

C SETON LR 


The RPG II program above displays the string 'REP HEAD' on the terminal. 
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Integer and floating-point procedure (cont’d.) 
LIB$POLYH • 9-12 
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Jacket procedure*9-1 


K 
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in keyword table*RTL-199 
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LIB$DISABLE_CTRL • 9-9, RTL-95 

LIB$DO_COMMAND • 9-7, RTL-97 

LIBSEDIV • RTL-99 

LIBSEMODD • RTL-101 

LIBSEMODF • RTL-101 

LIBSEMODG • RTL-101 

LIBSEMODH* RTL-101 

LIB$EMUL • RTL-104 

LIB$ENABLE_CTRL • 9-9, RTL-106 

LIB$ESTABLISH* 7-3, 7-13, 7-20, RTL-108 

LIBSEXTV* RTL-110 

LIBSEXTZV* RTL-113 

LIBSFFC* RTL-115 

LIBSFFS* RTL-115 

LIB$FILE_SCAN* RTL-117 

LIB$FILE_SCAN_END* RTL-119 

LIB$FIND_FILE* RTL-121 

LIB$FIND_FILE_END • RTL-124 

LIB$FIND_IMAGE_SYMBOL* RTL-125 

LIB$FIXUP_FLT • 7-30, RTL-128 

LIB$FLT_UNDER • 2-7, 7-31, RTL-130 

LIB$FREE_EF • RTL-132 

LIB$FREE_LUN • RTL-133 

LIB$FREE_TIMER • RTL-134 

LIB$FREE_VM • 8-3, RTL-135 

LIB$FREE_VM_PAGE • 8-3, RTL-137 

LIB$GET_COMM AND • RTL-139 

LIB$GET_COMMON • 9-5, 9-36, RTL-142 

LIB$GET_EF • RTL-148 

LIB$GET_FOREIGN • 9-3, RTL-150 

LIB$GET_INPUT *2-3, 5-8, RTL-154 

LIB$GET_LUN • RTL-160 

LIB$GET_SYMBOL • 9-8, RTL-164 

LIB$GET_VM • 5-3, 8-3, RTL-167 

LIB$GET_VM_PAGE • 8-3, RTL-169 

LIB$GETDVI • RTL-144 

LIB$GETJPI • RTL-156 

LIBSGETSYI • RTL-161 

LIBSICHAR* RTL-171 

LIB$INDEX* RTL-173 

LIB$INIT_TIMER • RTL-175 

LIBSINITIALIZE • 2-1, 10-1 

LIB$INSERT_TREE • 9-32, RTL-177 

LIBSINSQHI • RTL-187 

LIB$INSQTI • RTL-190 

LIBSINSV • RTL-192 

LIB$INT_OVER *7-31, RTL-194 

LIB$LEN • RTL-196 

LIB$LOCC • RTL-197 

LIB$LOOKUP_KEY • RTL-199 

LIB$LOOKUP_TREE • 9-32, RTL-203 

LIB$LP_LINES • RTL-205 
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LIB$MATCH_COND # 7-10, 7-29, RTL-210 
LIBSMATCHC • RTL-208 
LIBSMOVC3 • RTL-213 
LIB$MOVC5 • RTL-214 
LIB$MOVTC« RTL-216 
LIB$MOVTUC • RTL-228 
LIBSPAUSE • RTL-228.2 
LIBSPOLYD • RTL-229 
LIB$POLYF • RTL-229 
LIB$POLYG • RTL-229 
LIBSPOLYH* RTL-229 
LIB$PUT_COMMON • 9-5, 9-36, RTL-232 
LIB$PUT_OUTPUT • RTL-234 
LIB$RADIX_POINT »RTL-236 
LIB$REMQHI • RTL-238 
LIBSREMQTI • RTL-240 
LIB$RENAME_FILE • RTL-242 
LIB$RESERVE_EF • RTL-250 
LIB$RESET_VM_ZONE *8-13, 8-14, RTL-252 
LIB$REVERT • 7-3, 7-20, RTL-253 
LIB$RUN_PROGRAM • 9-5, RTL-254 
LIB$SCANC • RTL-256 
LIB$SCOPY_DXDX • 5-7, RTL-258 
LIB$SCOPY_R_DX • RTL-260 
LIB$SET_LOGICAL • 9-8, RTL-262 
LIB$SET_SYMBOL • 9-8, RTL-265 
LIBSSFREE1 _DD • RTL-268 
LIB$SFREEN_DD • RTL-269 
LIB$SGET 1 _DD • RTL-271 
LIB$SHOW_TIMER • 2-2, RTL-273 
LIB$SHOW_VM • RTL-277 
LIB$SIG_TO_RET • 7-29, RTL-283 
LIB$SIG_TO_STOP»7-29, RTL-285 
LIB$SIGNAL»2-1, 7-3, 7-7, 7-10, 7-11, 7-12, 7- 
15, 7-16, 7-22, 7-24 to 7-26, 7-31, RTL-280 
LIB$SIM_TRAP • 7-22, 7-29, RTL-287 
LIB$SKPC • RTL-289 
LIBSSPANC • RTL-291 
LIBSSPAWN • 9-9, RTL-294 
LIBSST AT—TIMER • RTL-299 
LIB$STAT_VM» RTL-303 

LIB$STOP*7-3, 7-4, 7-7, 7-10, 7-12, 7-15, 7-16, 
7-21, 7-22, 7-24 to 7-26, RTL-305 
LIBSSUBX • RTL-308 
LIB$SYS_ASCTIM • RTL-310 
LIB$SYS_FAO • RTL-312 
LIB$SYS_FAOL • RTL-314 
LIB$SYS_GETMSG • RTL-316 
LIB$SYS_TRNLOG • RTL-319 
LIBSTPARSE • RTL-322 
LIB$TR A _ASC_EBC • RTL-360 
LIB$TRA_EBC_ASC • RTL-363 


LIB$TRAVERSE_TREE • 9-32, RTL-365 
LIB$TRIM_FILESPEC • RTL-367 
LIBSWAIT • RTL-370 
Logarithm 

base 2 • RTL-429 
common • RTL-431 
natural *RTL-427 
natural complex*RTL-401 
Logical name • RTL-262, RTL-319 
deleting *RTL-88 
Logical unit number 
allocating *9-17 
RTL routine to free *RTL-133 


M 


Mailbox *9-24, RTL-6 
MATCHC (Match Characters) instruction 
RTL routine to access • RTL-208 
Mathematics procedure *4-1 
algorithm • 4-2 
calling convention • 4-2 
complex number *4-3 
condition handling *4-3 
entry point name *4-1 
JSB entry point *4-2 

Mechanism argument vector* 7-7, 7-12, 7-21 
Memory 

allocating pages of *8-4 
freeing pages of *8-4 
Memory allocation • 8-1 
algorithms* 8-6 
Memory fragmentation • 8-5 
Memory management system services *8-3 
Message Utility (MESSAGE) • 7-26 to 7-28 
Minimal screen update *3-21 
MOVC3 (Move Character 3 Operand) instruction 
RTL routine to access • RTL-213 
MOVC5 (Move Character 5 Operand) instruction 
RTL routine to access*RTL-214 
MTH$ABS • 4-4 
MTH$ACOS • RTL-372 
MTHSACOSD • RTL-375 
MTH$ AIMAG • RTL-425 
MTH$AIM AXO • 4-5 
MTH$ AIMINO • 4-6 
MTH$AINT *4-5 
MTH$AJM AXO • 4-5 
MTH$ AJMINO • 4-6 
MTH$ ALOG • RTL-427 
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MTH$ ALOG10 • RTL-431 
MTH$ ALOG2 • RTL-429 
MTHSAMAX1 «4-5 
MTH$AMIN1 »4-6 
MTH$ AMOD • 4-6 
MTHSANINT *4-6 
MTH$ASIN • RTL-378 
MTH$ ASIND • RTL-380 
MTH$AT AN • RTL-382 
MTHSATAN2 • RTL-386 
MTH$ ATAND • RTL-384 
MTH$ ATAND2 • RTL-388 
MTH$ATANH • RTL-390 
MTHSC ABS • RTL-392 
MTH$CCOS • RTL-395 
MTHSCDABS • RTL-392 
MTHSCDCOS • RTL-395 
MTH$CDEXP • RTL-398 
MTH$CDLOG • RTL-401 
MTHSCDSIN • RTL-414 
MTHSCDSQRT • RTL-416 
MTHSCEXP* RTL-398 
MTHSCGABS* RTL-392 
MTHSCGCOS* RTL-395 
MTH$CGEXP» RTL-398 
MTH$CGLOG • RTL-401 
MTHSCGSIN* RTL-414 
MTHSCGSQRT • RTL-416 
MTHSCLOG • RTL-401 
MTH$CMPLX • RTL-403 
MTHSCONJG • RTL-406 
MTHSCOS • RTL-408 
MTHSCOSD • RTL-410 
MTHSCOSH* RTL-412 
MTHSCSIN* RTL-414 
MTHSCSQRT • RTL-416 
MTH$CVT_D_G • RTL-419 
MTH$CVT_DA_GA • RTL-420 
MTHSC VT_G_D • RTL-419 
MTHSCVT_GA _D A • RTL-420 
MTHSDABS • 4-4 
MTHSDACOS • RTL-372 
MTHSD ACOSD • RTL-375 
MTHSDASIN • RTL-378 
MTHSD ASIND • RTL-380 
MTHSD ATAN • RTL-382 
MTHSD AT AN2 • RTL-386 
MTH$DATAND • RTL-384 
MTHSD AT AND2 • RTL-388 
MTHSDATANH • RTL-390 
MTHSDBLE • 4-4 
MTHSDCMPLX • RTL-403 


MTHSDCONJG • RTL-406 
MTHSDCOS • RTL-408 
MTHSDCOSD • RTL-410 
MTHSDCOSH* RTL-412 
MTHSDDIM • 4-4 
MTHSDEXP • RTL-422 
MTHSDFLOOR • 4-5 
MTHSDFLOTI • 4-5 
MTHSDFLOTJ • 4-5 
MTH$DIM«4-4 
MTHSDIM AG • RTL-425 
MTHSDINT *4-5 
MTHSDLOG • RTL-427 
MTHSDLOG10 • RTL-431 
MTHSDLOG2* RTL-429 
MTHSDMAX1 »4-6 
MTHSDMIN1 «4-6 
MTHSDMOD • 4-6 
MTHSDNINT »4-6 
MTHSDPROD • 4-7 
MTHSDRE AL • RTL-435 
MTHSDSIN • RTL-437 
MTHSDSINCOS • RTL-439 
MTHSDSINCOSD • RTL-442 
MTHSDSIND • RTL-445 
MTHSDSINH • RTL-447 
MTHSDSQRT • RTL-450 
MTHSDT AN • RTL-452 
MTHSDTAND • RTL-454 
MTHSDTANH • RTL-456 
MTHSEXP • RTL-422 
MTHSFLOATI • 4-5 
MTHSFLOATJ • 4-5 
MTHSFLOOR • 4-5 
MTH$G ABS • 4-4 
MTHSGACOS* RTL-372 
MTHSGACOSD • RTL-375 
MTHSGASIN • RTL-378 
MTHSG ASIND • RTL-380 
MTHSGATAN • RTL-382 
MTHSG AT AN2 • RTL-386 
MTHSG ATAND • RTL-384 
MTHSG AT AND2 • RTL-388 
MTHSGAT ANH • RTL-390 
MTHSGCMPLX • RTL-403 
MTHSGCONJG • RTL-406 
MTHSGCOS • RTL-408 
MTHSGCOSD • RTL-410 
MTHSGCOSH* RTL-412 
MTHSGDBLE • 4-4 
MTHSGDIM • 4-4 
MTHSGEXP • RTL-422 
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MTHSGFLOOR • 4-5 
MTHSGFLOTI • 4-5 
MTHSGFLOT J • 4-5 
MTH$GIM AG • RTL-425 
MTH$GINT • 4-5 
MTH$GLOG • RTL-427 
MTHSGLOG10 • RTL-431 
MTHSGLOG2 • RTL-429 
MTHSGMAX1 »4-6 
MTHSGMIN1 »4-6 
MTH$GMOD • 4-6 
MTHSGNINT «4-6 
MTH$GPROD • 4-7 
MTHSGRE AL • RTL-435 
MTHSGSIGN • 4-7 
MTHSGSIN • RTL-437 
MTHSGSINCOS • RTL-439 
MTHSGSINCOSD • RTL-442 
MTH$GSIND • RTL-445 
MTHSGSINH • RTL-447 
MTHSGSQRT • RTL-450 
MTH$GT AN • RTL-452 
MTH$GTAND • RTL-454 
MTHSGTANH • RTL-456 
MTH$HABS • 4-4 
MTH$H ACOS • RTL-372 
MTHSHACOSD • RTL-375 
MTH$HASIN • RTL-378 
MTH$H ASIND • RTL-380 
MTH$H AT AN • RTL-382 
MTH$H ATAN2 • RTL-386 
MTHSHATAND • RTL-384 
MTHSHATAND2 • RTL-388 
MTH$H ATANH • RTL-390 
MTH$HCOS • RTL-408 
MTH$HCOSD • RTL-410 
MTH$HCOSH • RTL-412 
MTH$HDIM • 4-4 
MTHSHEXP • RTL-422 
MTHSHFLOOR • 4-5 
MTHSHINT »4-5 
MTH$HLOG • RTL-427 
MTHSHLOG10 • RTL-431 
MTHSHLOG2 • RTL-429 
MTHSHMAX1 *4-6 
MTH$HMIN1 »4-6 
MTHSHMOD • 4-6 
MTH$HNINT *4-7 
MTHSHSIGN • 4-7 
MTHSHSIN* RTL-437 
MTHSHSINCOS • RTL-439 
MTH$HSINCOSD • RTL-442 


MTHSHSIND* RTL-445 
MTHSHSINH* RTL-447 
MTHSHSQRT* RTL-450 
MTH$HTAN« RTL-452 
MTHSHT AND • RTL-454 
MTH$HTANH • RTL-456 
MTH$II ABS • 4-4 
MTHSlIAND • 4-4 
MTH$IIDIM«4-4 
MTH$IIDINT »4-5 
MTH$IIDNNT • 4-6 
MTHSllEORM-4 
MTH$IIFIX«4-4 
MTH$IIGINT»4-5 
MTH$IIGNNT *4-6 
MTH$IIHINT »4-5 
MTHSIIHNNT »4-7 
MTH$IINT *4-5 
MTH$IIOR»4-5 
MTH$IISHFT *4-7 
MTHSHSIGN *4-7 
MTHSIM AXO • 4-5 
MTHSIMAX1 »4-6 
MTHSIMINO • 4-6 
MTHSIMIN1 «4-6 
MTHSIMOD • 4-6 
MTHSININT *4-7 
MTHSINOT «4-7 
MTHSJI ABS • 4-4 
MTHSJI AND • 4-4 
MTHSJIDIM • 4-4 
MTHSJIDINT »4-5 
MTHSJIDNNT • 4-6 
MTHSJIEOR • 4-4 
MTH$JIFIX*4-4 
MTHSJIGINT «4-5 
MTHSJIGNNT *4-7 
MTHSJIHINT *4-5 
MTHSJIHNNT *4-7 
MTHSJINT • 4-5 
MTH$JIOR«4-5 
MTHSJISHFT »4-7 
MTHSJISIGN • 4-7 
MTHSJMAXO • 4-5 
MTHSJMAX1 »4-6 
MTHSJMINO • 4-6 
MTHSJMIN1 »4-6 
MTH$ JMOD • 4-6 
MTHSJNINT • 4-7 
MTHSJNOT *4-7 
MTHSRANDOM • RTL-433 
MTHSREAL* RTL-435 
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MTH$SGN*4-7 
MTH$SIGN*4-7 
MTHSSIN • RTL-437 
MTH$SIN _R4 • 2-5 
MTHSSINCOS • RTL-439 
MTH$SINCOSD • RTL-442 
MTH$SIND • RTL-445 
MTFISSINH • RTL-447 
MTH$SNGL • 4-7 
MTH$SNGLG • 4-7 
MTH$SQRT • RTL-450 
MTHSTAN • RTL-452 
MTHST AND • RTL-454 
MTH$T ANH • RTL-456 
MTHSUM AX • RTL-458 
MTH$UMIN • RTL-459 
Multiplication • RTL-101 

extended precision • RTL-104 
of complex number*RTL-506 



Octal text 

converting to binary • RTL-54 
OTSSCNVOUT • RTL-472 
OTS$CNVOUT_G • RTL-472 
OTS$CNVOUT_H • RTL-472 
OTSSC VT_L _TB • RTL-460 
0TS$C VT_L _TI • RTL-462 
0TS$CVT__L _TL • RTL-464 
OTSSC VT_L _TO • RTL-466 

OTSSC VT_I_TU • RTL-468 

OTSSC VT_L_TZ • RTL-470 
OTSSC VT_T_z • RTL-485 
OTS$CVT_TB_L • RTL-474 
OTS$CVT_TI_L* RTL-477 

OTSSC VT_TI_L* RTL-479 

OTSSC VT_TO_L • RTL-481 
OTSSC VT_TU_L* RTL-483 
OTS$CVT_TZ_L* RTL-489 
OTS$DIV_PK_LONG • RTL-495 
OTS$DIV_PK_SHORT • RTL-499 
OTSSDIVC • RTL-492 
OTS$DIVCD_R3 • RTL-492 
OTSSDIVCG—R3 • RTL-492 
OTSSMOVE3 • RTL-502 
OTSSMOVE5 • RTL-504 
OTS$MULCD_R3 • RTL-506 
OTS$MULCG_R3 • RTL-506 
OTSSPOWCxCx • RTL-508 


OTSSPOWCxJ • RTL-511 
OTSSPOWDLU • RTL-524.1 
OTSSPOWDx • RTL-513 
OTSSPOWGG • RTL-516 
OTSSPOWGJ • RTL-516 
OTSSPOWGLU • RTL-524.1 
OTSSPOWHLU—R3 • RTL-524.1 
OTSSPOWHx* RTL-519 
OTSSPOWII • RTL-522 
OTSSPOWJJ • RTL-523 
OTSSPOWLULU • RTL-524 
OTSSPOWRLU • RTL-524.1 
OTSSPOWRx • RTL-524.3 
OTS$SCOPY_DXDX* 5-7, RTL-528 
OTS$SCOPY_R_DX • RTL-530 
OTSSSFREE1 _DD • RTL-533 
OTS$SFREEN_DD • RTL-534 
OTSSSGET1 _DD • RTL-535 
Output formatting control procedure • 9-21 
LIBSCURRENCY • 9-21 
LIB$DIGIT_SEP • 9-21 
LIB$LP_LINES • 9-21 
LIB$RADIX_POINT *9-21 
Output operation 
batching of *3-21 



Passing mechanism 
by descriptor*2-7 
by reference • 2-6 
by value • 2-6 
for arrays • 2-9 
for scalars • 2-8 
for strings *2-9 
Pasteboard • 3-2.2 

Performance measurement procedure • 9-18 
LIB$FREE_TIMER *9-18 
LIB$INIT_TIMER *9-18 
LIB$SHOW_TIMER *9-18 
LIBSST AT—TIMER *9-18 
Polynomial 

evaluating • RTL-229 
Procedure 

See also Entry point 

See also Mathematics procedure 

See also Screen management 

See also String manipulation procedure 

class and data type *2-10 

cross-reference *1-4 
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Procedure (cont'd.) 
definition of* 1-1 
general utility* 1-4 
how to call* 1-3, 2-1, 2-2 
language-independent support* 1-4 
mathematics* 1-4 

processwide resource allocation • 9-16, 9-17 
resource allocation* 1-4 
screen management* 1-4 
signaling and condition handling* 1-4 
syntax analysis* 1-4 
variable-length bit field procedure*9-10 
Procedures 

See also DECtalk procedure 
$PUTMSG* 7-4, 7-14, 7-17, 7-27 


Q 


Run-Time Library procedure (cont'd.) 
jacket procedure*9-1 
language-independent support* 1-4 
language support* 1-3 
mathematics* 1-4 
output formatting control *9-21 
performance measurement *9-18 
resource allocation* 1-4 
screen management* 1-4, 3-1 
signaling and condition handling* 1-4 
string manipulation • 5-1 
syntax analysis* 1-4 
system service access *9-1 
to access VAX/VMS system components • 9-1 
to access command language interpreter*9-2 
to access VAX instruction set *9-9 
to manipulate character string *9-14 
variable-length bit field instruction • 9-10 


Queue *9-13, RTL-190 
entry insertion *RTL-187 
self-relative* 9-13 
Queue access procedure *9-13 
LIB$INSQHI *9-13 
LIB$INSQTI*9-13 
LIBSREMQHI *9-13 
LIB$REMQTI *9-13 


R 


Random number generator*RTL-433 
Reserved operand 

fix floating-point fault*RTL-128 
Run-Time Library 
capabilities of* 1-1 
condition handling *7-1 
described* 1-1 
linking with* 1-2 
organization of* 1-3 
queue access *9-13 
Run-Time Library procedure 
cross-reference *1-4 
date/time utility *9-22 
defined *1-1 

entry point *2-3, 2-4, 2-5 

general purpose* 1-3 

general utility* 1-4 

how to call* 1-3, 2-1, 2-2 

integer and floating-point*9-12 

interaction with operating system *9-1 


s 


SCANC (SCAN Characters) instruction 
RTL routine to access*RTL-256 
Screen management • 3-1 

changing the current rendition of a virtual 
display *3-12 

character-oriented output *3-12 
composition operations*3-5 
controlling asynchronous actions *3-22 
deletion operations *3-11 
erasure operations • 3-11 
if state • 3-20 

inputing through virtual keyboard • 3-15 
insertion operations *3-11 
line drawing *3-14 
line-oriented output *3-12 
minimal screen update *3-21 
operational controls *3-20 
rendition • 3-4 
state • 3-20 
terminator *3-15 
virtual display *3-3, 3-10 
virtual keyboard *3-5 
writing operations*3-12 
Screen management procedure 
pasteboard *3-2.2 
Shareable image* 1-2 
activating • RTL-125 

Signal argument vector*7-7, 7-10, 7-21 
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Sign-extended longword field •RTL-110 
Sine 

complex • RTL-414 
hyperbolic • RTL-447 
in degrees *RTL-442, RTL-445 
in radians • RTL-437, RTL-439 
SMG$ADD_KEY_DEF *3-19, RTL-538 
SMGS ALLOW—ESCAPE • RTL-541 
SMG$BEGIN_DISPLAY_UPDATE • 3-22, RTL-543 
SMGSBEGIN —PASTEBOARD—UPDATE • 3-22, 
RTL-544 

SMGSCANCEI_INPUT*3-5, RTL-545 

SMG$CHANGE_PBD_CH ARACTERISTICS • 3-3, 
RTL-546 

SMGSCH ANGE-RENDITION *3-13, RTL-549 

SMG$CHANGE_VIRTUAI_DISPLAY • 3-13, RTL- 

552 

SMG$CHECK_FOR_OCCLUSION • 3-9, RTL-555 
SMGSCONTROL _MODE • 3-20, RTL-559 
SMG$COPY_VIRTUAL—DISPLAY • RTL-560.2 
SMGSCREATE_KEY_TABLE *3-19, RTL-561 
SMG$CREATE_PASTEBOARD • 3-2.2, 3-25, 
RTL-562 

SMGSCREATE_VIRTUAL—DISPLAY • 3-4, RTL- 
565 

SMGSCREATE—VIRTUAL—KEYBOARD *3-5, 
RTL-569 

SMGSCURSOR—COLUMN • 3-10, RTL-573 
SMGSCURSOR—ROW • 3-10, RTL-574 
SMGSDEFINE—KEY*3-19, RTL-575 
SMGSDEL—TERM—TABLE • RTL-576.1 
SMGSDELETE—CHARS *3-11, RTL-577 
SMGSDELETE—KEY—DEF • 3-19, RTL-581 
SMGSDELETE—LINE *3-11, RTL-583 
SMGSDELETE—PASTEBOARD • 3-3, RTL-586 
SMGSDELETE—VIRTUAL -DISPLAY • 3-4, 3-8, 
3-24, RTL-587 

SMGSDELETE—VIRTUAL -KEYBOARD • RTL-588 
SMGSDISABLE—BROADCAST—TRAPPING • RTL- 
589 

SMGSDISABLE—UNSOLICITED—INPUT • RTL-598 
SMGSDRAW_LINE *3-14, RTL-600 
SMGSDRAW_RECTANGLE • 3-14, RTL-600.4 
SMGSENABLE—UNSOLICITED—INPUT • 3-23, 
RTL-600.8 

SMGSEND—DISPLAY—UPDATE • 3-22, RTL- 
600.10 

SMGSEND—PASTEBOARD—UPDATE • 3-22, RTL- 
601 

SMGSERASE—CHARS *3-11, RTL-602 
SMGSERASE—DISPLAY *3-11, RTL-606 
SMGSERASE—LINE • 3-11, RTL-610 
SMGSERASE-PASTEBOARD • 3-3, RTL-614 


SMGSFIND—CURSOR—DISPLAY • RTL-616 
SMGSFLUSH—BUFFER • 3-21, RTL-617 
SMGSGET—BROADCAST—MESSAGE • 3-23, RTL- 
618 

SMG$GET_CHAR_AT_PHYSICAL-CURSOR* 
RTL-620 

SMGSGET—DISPLAY—ATTR • RTL-622 
SMGSGET—KEY—DEF • RTL-624 
SMGSGET—KEYBOARD—ATTRIBUTES • RTL-627 
SMGSGET—NUMERIC—DAT A • RTL-629 
SMGSGET—PASTEBOARD—ATTRIBUTES • 3-3, 
RTL-630.1 

SMGSGET—PASTING—INFO • RTL-630.3 
SMGSGET—TERM—DAT A • RTL-631 
SMGSHOME—CURSOR *3-11, RTL-633 
SMGSINIT—TERM—T ABLE • RTL-635 
SMGSINIT—TERM—T ABLE—BY_TYPE • RTL-637 
SMGSINSERT—CHARS *3-12, RTL-639 
SMGSINSERT—LINE *3-12, RTL-644 
SMGSINVALID ATE—DISPLAY • RTL-649 
SMGSLABEL -BORDER • RTL-650 
SMGSLIST—KEY—DEFS • RTL-655 
SMGSLOAD—KEY—DEFS *3-19, RTL-658 

SMGSMOVE—VIRTUAl_DISPLAY • 3-7, RTL-660 

SMGSPASTE—VIRTUAl_DISPLAY • 3-5, RTL-662 

SMGSPOP-VIRTUAL-DISPLAY *3-8, 3-24, RTL- 
665 

SMGSPUT—CHARS *3-12, RTL-667 
SMGSPUT—CHARS—HIGH WIDE *3-12, RTL-671 
SMGSPUT—CHARS—WIDE *3-12, RTL-674 
SMGSPUT—LINE *3-12, RTL-677 
SMGSPUT—LINE—HIGHWIDE • RTL-684 
SMGSPUT—LINE—WIDE *3-12, RTL-687 
SMGSPUT—PASTEBOARD • RTL-692 

SMGSPUT—VIRTU Al_DISPLAY—ENCODED • RTL- 

694 

SMGSPUT—WITH—SCROLL* RTL-697 
SMGSREAD—COMPOSED—LINE • 3-5, 3-16, 3-19, 
RTL-701 

SMGSREAD—FROM—DISPLAY *3-15, RTL-706 
SMGSRE AD_KEYSTROKE • RTL-710 
SMGSREAD—STRING • 3-5, 3-16, RTL-717 
SMGSREAD—VERIFY • RTL-726 
SMGSREPAINT—LINE • RTL-732 
SMGSREPAINT—SCREEN • RTL-734 
SMGSREPASTE—VIRTUAL—DISPLAY• 3-7, RTL- 
737 

SMGSRESTORE—PHYSIC Al_SCREEN • 3-26, 

RTL-744 

SMGSRETURN—CURSOR—POS *3-10, RTL-744.2 
SMGSRETURN—INPUT—LINE • RTL-744.4 
SMGSRING—BELL* RTL-744.6 
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SMG$SAVE_PHYSICAL—SCREEN • 3-26, RTL- 
744.7 

SMGSSCROLL -DISPLAY-AREA • RTL-744.9 
SMGSSET—BROADCAST—TRAPPING • 3-23, RTL- 
744.12 

SMGSSET—CURSOR—ABS *3-11, RTL-744.14 
SMGSSET—CURSOR—REL*3-11, RTL-745 
SMGSSET—DEFAULT—ST ATE • RTL-747 
SMGSSET-DISPL AY_SCROLL -REGION • RTL-749 
SMGSSET—KEYPAD—MODE • RTL-751 
SMGSSET—OUT—OF—BAND—ASTS • 3-23, RTL- 
753 

SMGSSET—PFIYSICAL -CURSOR • RTL-755 
SMGSSNAPSHOT »3-23, RTL-757 
SMGSUNPASTE—VIRTUAL—DISPLAY• 3-6, 3-24, 
RTL-758 

Square root*RTL-450 

State • 3-20 

STRSADD • RTL-760 

STR$ANALYZE_SDESC • 5-4, RTL-764 

STR$APPEND • 5-9, RTL-766 

STR$CASE_BLIND_COMPARE • RTL-768 

STRSCOMPARE *2-16, RTL-770 

STR$COMPARE_EQL*2-16, RTL-772 

STRSCOMPARE _MULTI • RTL-774 

STRSCONCAT • 5-9, RTL-776 

STR$COPY_DX • 5-7, 5-8, RTL-779 

STRSCOPY—R • RTL-781 

STRSDIVIDE • RTL-783 

STRSDUPL -CHAR • RTL-787 

STRSFIND—FIRST—IN_SET • RTL-789 

STRSFIND—FIRST—NOT—IN_SET • RTL-791 

STR$FIND_FIRST_SUBSTRING • RTL-793 

STRSFREE1 _DX • RTL-796 

STRSGET1 _DX • RTL-797 

STRSLEFT • 5-9, RTL-799 

STRSLEN—EXTR • RTL-802 

STRSM ATCH-WILD • RTL-805 

STRSMUL • RTL-807 

STRSPOS—EXTR • 5-9, RTL-813 

STRSPOSITION • RTL-81 1 

STRSPREFIX • 5-9, RTL-816 

STRSRECIP* RTL-818 

STRSREPLACE • RTL-822 

STRSRIGHT • 5-9, RTL-825 

STRSROUND • RTL-828 

STRSTRANSLATE • RTL-831 

STRSTRIM • RTL-834 

STRSUPC ASE • RTL-836 

String 

See also Descriptor 

See also String manipulation procedure 


String (cont'd.) 

allocating *RTL-535 

appending source string to end of destination 
string • RTL-766 

comparing for equality, no padding • RTL-772 
comparing two*RTL-770 
comparing without regard to case*RTL-768 
concatenating • RTL-776 
converting to uppercase • RTL-836 
copying by descriptor• RTL-258, RTL-528, 
RTL-779, RTL-781 

copying by reference • RTL-260, RTL-530 

divide two decimal strings • RTL-783 

dynamic length • 5-2, 5-3, 5-11, 5-12 

evaluation rules*5-1 

finding substring • RTL-811 

fixed length* 5-1 

free • RTL-534 

inserting source string at front of destination* 
RTL-816 

maximum length of *5-1 
null string *5-11 
output length argument *5-8 
reciprocal of decimal string • RTL-818 
removing trailing blanks and tabs*RTL-834 
rounding or truncating a decimal string •RTL- 
828 

semantics of *5-1, 5-4 
skipping characters in*RTL-291 
translating matched characters in*RTL-831 
varying length*5-2 
String arithmetic • RTL-760 

division of decimal strings • RTL-783 
multiplication • RTL-807 
String descriptor • RTL-4, RTL-764 
String manipulation procedure*5-1 

descriptor classes and string semantics • 5-4 
how to select • 5-8 
list of severe errors *5-11 
reading input string arguments • 5-5 
writing output string arguments • 5-6 
Subprocess 

connecting to using LIB$ATTACH • 9-9 
creation of using LIB$SPAWN • 9-9 
Substring • 5-1 

replacing • RTL-822 
Subtraction 

two's complement*RTL-308 
System service access *9-1, 9-2 


Index-11 


Index 


T 


Tangent • RTL-452, RTL-454 
hyperbolic • RTL-456 
Terminator*3-16 



$UNWIND* 7-15, 7-21, 7-22, 7-29 
User procedure*2-1 



Variable-length bit field *9-10 
VAX instruction set 

accessing through Run-Time Library *9-9 
Virtual display • 3-3 

outputting through *3-10 
Virtual keyboard *3-5 
VMS usage* 1-10 



Zone* 8-6 

allocation algorithm • 8-14 
attribute* 8-7 
creating • 8-6 
deleting *8-6 
identifier* 8-1 1 
resetting *8-13 
the default zone *8-11 
user-created • 8-6 
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